Limits

A limit is a value the control plane or an agent enforces. This page lists each one, grouped by the area where you meet it. A value marked as a default is not a limit: you can change it, and it is listed so you know what applies when you set nothing.

Where a row names an HTTP status, the API answers with that status and a message naming the field. A 422 means the request is well formed but a value is out of range. A 409 means the request collides with the current state.

API and paginationCopy Anchor Link

Limits on the size of a request and on how much one list call returns.

Limit	Value	Applies to
List page size, default	50 items	A list request that sets no limit.
List page size, range	1 to 200 items	A limit outside the range answers 422.
Build log page size, default	200 lines	A build log request that sets no limit.
Build log page size, range	1 to 1,000 lines	A limit outside the range answers 422.
SCIM list page size	At most 200 resources	A count above 200 is clamped to 200.
Deployments-per-day report window	1 to 400 days	A days value outside the range answers 422. The default is 371 days.
Request body	At most 1 MiB	The body of an API, SCIM or agent request. A larger body is refused with 413. The agent's log batches have their own limit, listed under Observability and retention.
Staged changes per batch	At most 500 items	A batch of staged changes with more items, or none, answers 422.
Canvas positions per request	At most 500 items	A request that saves more canvas positions answers 422.

Live streamsCopy Anchor Link

Limits on the server-sent event streams that feed the console and the log views. The deployment stream, the environment log stream and the build log stream share one set of limits. The organization event stream has its own.

Limit	Value	Applies to
Open log, build log and deployment streams	At most 4 per user or API token	A fifth stream opens, sends one refused: comment and closes.
Log, build log and deployment stream lifetime	15 minutes	The server ends the stream. The console reconnects.
Log, build log and deployment stream heartbeat	Every 5 seconds	The server sends a comment frame so that proxies keep the connection open.
Log, build log and deployment stream re-authorization	Every 30 seconds	A revoked session or token, or a lost grant, ends the stream within 30 seconds.
Open organization event streams	At most 8 per user or API token	A ninth stream opens, sends one refused: comment and closes.
Organization event stream lifetime	30 minutes	The server ends the stream. The console reconnects.
Organization event stream keep-alive	Every 15 seconds	The server sends a comment frame so that proxies keep the connection open.
Organization event stream re-authorization	Every 30 seconds	A revoked session or token, or a lost grant, ends the stream within 30 seconds.
Console reconnect delay	1 second, doubling to at most 30 seconds	The console waits this long before it reopens a stream that dropped.

Rate limitsCopy Anchor Link

Limits per client address on unauthenticated endpoints, including the ones that connect a cluster. Each bucket refills continuously. A request over the limit answers 429.

Limit	Value	Applies to
Sign-in start and callback	20 requests at once, then 1 more every 3 seconds	One bucket per client address for both sign-in endpoints.
Agent enrollment and host scripts	5 requests per minute	One shared bucket per client address for agent enrollment and for the install, high-availability, Tailscale and CloudNativePG script requests.
Install progress reports	60 requests per minute	One bucket per client address for the progress reports an installing node posts.
Mesh registration	5 requests per minute	One bucket per client address for a machine that asks to join the WireGuard mesh.
Community template refresh	1 refresh every 30 seconds	One bucket for the whole installation. A request while a refresh runs, or within 30 seconds of the last one, answers 429.

Services and processesCopy Anchor Link

Limits that apply when you configure a service in the console or over the API. For the limits of a nebula.toml file, see the next section. For the model behind them, see processes.

Limit	Value	Applies to
Process port	1 to 65,535	The port of an http process, or of a worker process that declares one. A value outside the range answers 422.
Replicas	0 or more, except a managed Postgres database, which takes 1 to 6	A negative value answers 422. For any other service the API sets no upper bound. The console control stops at 50 and nebula.toml stops at 100. A Postgres database has one writer and up to 5 readers, so staging 0 or more than 6 instances answers 422.
Run-as user ID	0 or more	A negative value answers 422.
Release command size	At most 8 KiB in total	The combined length of every argument. A longer command answers 422.
Release command timeout	1 to 3,600 seconds	A value outside the range answers 422. The default is 300 seconds.
Deploy after entries	At most 20	The services and databases one service waits for, as set in the console or API. A longer list answers 422. See deploy order.
Dockerfile build target	At most 128 characters	The stage name must start with a letter or digit and use letters, digits, _, . or -. A name outside the shape answers 422.
Retired releases kept per service	3	Older retired releases are removed from the cluster, so a rollback reaches the 3 newest.

nebula.tomlCopy Anchor Link

Limits on a service's nebula.toml file, as written in the guide. A file over any limit is invalid: the build fails and its log lists each problem with the key and line. Counts apply to the merged result after environment overrides.

Limit	Value	Applies to
File size	At most 64 KiB	The whole file. It is checked before it is parsed.
Processes	At most 20	Entries in [processes].
Process name	1 to 30 characters	Lowercase letters, digits and -, starting with a letter: ^[a-z][a-z0-9-]{0,29}$.
Mounts	At most 10	Entries in [[mounts]].
Mount name	1 to 30 characters	The same pattern as a process name.
Mount size	Greater than 0, at most 1 TiB	The initial size of a mount.
Environment variables	At most 100	Keys in env.
Environment variable key	Uppercase letters, digits and _	^[A-Z_][A-Z0-9_]*$. A key outside the shape is refused.
Build arguments	At most 50	Keys in [build] args.
String length	At most 4 KiB	Each string value and each cmd or entrypoint word, counted in bytes. release_command is not held to this limit word by word; only its 8 KiB total applies.
Release command size	At most 8 KiB in total	The combined length of every word of release_command.
Release command timeout	10 seconds to 1 hour	release_command_timeout. The default is 300 seconds when a command is set and no timeout.
Deploy after entries	At most 20	Slugs in [deploy] depends_on.
Port	1 to 65,535	A process port and a metrics port.
Replicas	0 to 100	A process replicas.
Run-as user ID	0 to 2,147,483,647	A process run_as_user.
Stabilization time	0 to 600 seconds	A process stabilization_seconds.
Drain time	0 to 600 seconds	A process drain_seconds.

Project configCopy Anchor Link

Limits on a project config: the nebula.toml at the root of a project's config repository. Each service block in it is also a service file, so the service file limits above apply to it. A value over a limit is reported as a problem that names the setting.

Limit	Value	Applies to
File size	At most 256 KiB	The whole file. It is checked before it is parsed.
Services and databases	At most 20 in total	Entries in [services] and [databases] together.
Service or database slug	1 to 40 characters	Lowercase letters and digits in single-hyphen-separated segments, starting with a letter. inputs is reserved.
Connection variables per service	At most 100	Keys in a service's connection table.
Secrets per service	At most 100	Keys in a service's secrets table.
Deploy after entries	At most 20	Slugs in a service's depends_on.
Postgres readers	0 to 5	readers in a Postgres database block.
Database initial size	Greater than 0, at most 1 TiB	size in a database block.

TemplatesCopy Anchor Link

Limits on a template file. A malformed template answers 422 and lists every problem it has. Previewing a template returns the problems in the response body instead.

Limit	Value	Applies to
File size	At most 256 KiB	A template saved, previewed, or fetched from a URL.
Name	1 to 60 characters	The template's name.
Slug	1 to 40 characters	Lowercase letters, digits and -, starting with a letter.
Description	1 to 280 characters	The template's description.
Tags	At most 8	Entries in tags.
Tag length	1 to 24 characters	Lowercase letters, digits and -, starting with a letter or digit.
Readme	At most 16 KiB	The template's readme.
Inputs	At most 20	Entries in inputs.
Input key	1 to 64 characters	An uppercase letter, then uppercase letters, digits and _.
Input label	1 to 60 characters	An input's label.
Input description	At most 280 characters	An input's description.
Services	1 to 20	Entries in services.
Service name	1 to 30 characters	Lowercase letters and digits in single-hyphen-separated segments, starting with a letter.
Processes per service	At most 10	Entries in a service's processes.
Process name	1 to 30 characters	Lowercase letters, digits and -, starting with a letter.
Volumes per process	At most 5	Entries in a process's volumes.
Volume name	1 to 30 characters	Lowercase letters, digits and -, starting with a letter.
Volume size	At most 1 TiB	A volume's size.
Variables per service	At most 100	Entries in a service's variables.
Port	1 to 65,535	A process port.
URL fetch time	10 seconds	Fetching a template from a URL. A slower response is refused.
URL redirects	At most 4	Fetching a template from a URL. A fifth redirect is refused, and so is a redirect to a URL that is not https.
Community catalog refresh, automatic	Every hour	The control plane reloads the public community templates.
Community catalog download	At most 8 MiB	The compressed download of one refresh. A larger download is refused.
Community catalog download time	30 seconds	One refresh download.
Community template file	At most 256 KiB	Each template file in the community catalog.

Compose importCopy Anchor Link

Limits on an import from a Compose file. An import over a hard limit is refused with 422. Where a row says the extra items are skipped, the import goes on and lists a note.

Limit	Value	Applies to
Compose file size	At most 256 KiB	A larger file is refused with 422.
Compose files found	At most 20	Files listed when the import searches the repository. The search covers the scan root and its immediate subfolders. Further files are not listed.
Subfolders searched	At most 50	The first 50 subfolders of the scan root, in alphabetical order. Hidden folders, node_modules and vendor are never searched.
Services per import	At most 20	Services ticked for one import. More answers 422. In a file with more services, the first 20 are ticked and the rest wait for a second import.
Service slug	1 to 30 characters	Lowercase letters and digits in single-hyphen-separated segments, starting with a letter.
Volumes kept per process	At most 5	Volumes beyond the fifth are not kept, and a note says their data is lost on redeploy.
Environment files read	At most 16	Distinct env_file files read across the whole Compose file. A file that several services name counts once. The variables of further files are not imported.
Environment file size	At most 64 KiB	Each env_file and each .env file. A larger file is not used.

Variables and filesCopy Anchor Link

Limits on variables, variable expressions and the files a service mounts.

Limit	Value	Applies to
Variable key	Uppercase letters, digits and _, not starting with a digit	^[A-Z_][A-Z0-9_]*$. A key outside the shape answers 422. The database enforces the same rule.
secret(N) length	16 to 128 characters	The N of a secret(N) expression. A value outside the range answers 422. The default is 32 characters.
Reference chain depth	At most 5	References that point at values that are themselves references. Saving a variable does not check the chain. A deeper chain, or a cycle, is refused when a deployment compiles the variables, and the request answers 400.
File mounts per service	At most 20	Variables mounted as files. More answers 422.

DatabasesCopy Anchor Link

Limits on a database service and on the console's query tab.

Limit	Value	Applies to
Query run time	5 seconds	One console query. A query over the limit is stopped.
Query rows	At most 500	Rows returned by one console query.
Query text	At most 16 KiB	A longer query answers 422.
Result cell	At most 2 KiB	A longer cell is cut and marked as cut.
Result size	At most 512 KiB	Once the cells of a result reach this size as JSON, the result stops growing.
Table listing time	5 seconds	The table list the Data tab loads.
Concurrent console commands	At most 4 per agent	A command over the limit is answered at once with a busy result and is not queued.
Database name	1 to 63 characters	The name in a create request. A name outside the range answers 422.
Database slug	At most 40 characters	The slug derived from the name. A longer slug answers 422.
Postgres instances	1 to 6	The replica count of a Postgres database: one writer and 0 to 5 readers. A value outside the range answers 422.
Daily dump retention, default	7 dumps	The schedule a new database gets keeps its 7 newest dumps.
Point-in-time recovery prefix	At most 256 characters	The archive prefix. It is a slash-separated path without spaces, backslashes or ... A longer prefix answers 422.
Restored service name	At most 63 characters	The name of the new service in a restore into a new service. A longer name answers 422.

Volumes and backupsCopy Anchor Link

Limits on volumes, their backups and restores.

Limit	Value	Applies to
Volume size	Greater than 0	A console volume, an environment override and the data volume of a new database. A size of 0 or less answers 422.
Backup schedules per volume and environment	1	A second schedule replaces the first.
Schedule retention	At least 1 backup	keepLast. A value below 1 answers 422. Older succeeded backups of the schedule are deleted after each new one succeeds.
Schedule expression	5 fields, evaluated in UTC	Minute, hour, day of month, month and day of week. Descriptors, a seconds field and a time zone override answer 422.
Backup archive size	At most 1,250 GiB	The compressed archive of one volume. A larger archive is deleted after upload, no backup is recorded and the backup fails.
Backup download link	15 minutes	A signed download URL stops working after this time.
Restore into a new service	Waits up to 2 hours	The restore waits for the new service to start, which includes image pull, volume creation and any approval. It fails after that time.
Object store check	15 seconds	The write, read and delete probe when you verify an object store. Adding or editing a store does not run it. A store that cannot finish the probe in this time is not verified, and the error is shown on the store.

BuildsCopy Anchor Link

Limits on builds from a git source.

Limit	Value	Applies to
Build run time	30 minutes	A build that runs longer fails.
Concurrent builds per cluster	At most 2	A third build waits in the queue.
Wait for a pushed image	15 minutes	A trigger-only service checks every 20 seconds. The build fails with a message that the tag did not appear when the tag is still missing after 15 minutes.
Build log line	At most 8 KiB	A longer line is truncated.
Build log retention	7 days	Build log lines older than 7 days are deleted. The sweep runs hourly.

Deployments and approvalsCopy Anchor Link

Limits on deployments, approvals and freezes, rollbacks and promotions and deploy order.

Limit	Value	Applies to
Approval wait	24 hours	A request nobody decides expires. The deployment it gates is cancelled.
Deploy concurrency per project	At least 1	A project that sets it refuses a deployment while that many are in flight, with 409. A project that sets nothing has no limit.
Deploy freeze windows	At most 28	Windows in an organization's freeze policy. More answers 422.
Change set message	At most 500 characters	A longer message answers 422.
Commits shown on an approval	At most 50	A longer comparison shows the 50 most recent commits.
Stage budget: pending	1 minute	A deployment that stays in the stage longer is flagged with the delivery or stalled blocker, whichever names the cause.
Stage budget: admitted	3 minutes	The same, for the admitted stage.
Stage budget: releasing	30 minutes	The same, for the releasing stage.
Stage budget: starting	10 minutes	The same, for the starting stage.
Stage budget: qualifying	7 minutes	The same, for the qualifying stage.
Stage budget: activating	4 minutes	The same, for the activating stage.
Stage budget: draining	20 minutes	The same, for the draining stage.
Qualifying timeout	5 minutes	A release whose readiness is unmet after 5 minutes fails with the readiness blocker.
Volume claim timeout	2 minutes	A volume claim that stays unbound fails with the pvc-attachment blocker.
Route activation timeout	2 minutes	A traffic switch that keeps failing fails with the route-activation blocker.
Drain restart threshold	3 restarts	A container of the new release that has restarted 3 or more times during the drain window, or a new release with fewer ready replicas than desired. Traffic goes back to the previous release and the new release fails with the readiness blocker.
Agent offline after	More than 1 minute without a heartbeat	A deployment that has stalled on a cluster whose agent is offline gets the delivery blocker.

Preview environmentsCopy Anchor Link

Limits on preview environments.

Limit	Value	Applies to
Idle lifetime	1, 3 or 7 days	A preview with no push for this long is deleted. Any other value answers 422. The default is 3 days.

DomainsCopy Anchor Link

Limits on domains.

Limit	Value	Applies to
Hostname	A valid RFC 1123 subdomain, at most 253 characters	A hostname outside the shape answers 422.
Unverified hostname reservation	7 days	An unverified public hostname stays reserved for this time. After it expires, the reservation can be replaced once a fresh DNS check allows it.
Tailnet device removal	10 minutes	The control plane removes a recorded device that no domain reports and the operator has not removed within this time.

ClustersCopy Anchor Link

Limits on clusters and their agents. For clusters that serve other clusters' domains, see edge clusters.

Limit	Value	Applies to
Clusters per organization	At most 16	The WireGuard address plan holds 16 clusters. Creating a 17th answers 409.
Enrollment token lifetime	1 hour	The token printed when you create a cluster.
Join command lifetime	300 seconds to 24 hours	A join command's ttlSeconds and the organization default. A value outside the range answers 422. The default is 1 hour.
Node labels per join command	At most 20	A longer map answers 422.
SSH port	1 to 65,535	The port of an install over SSH. The default is 22. A value outside the range answers 422.
SSH connection time	15 seconds	The TCP connect and SSH handshake of an install. A slower host fails.
SSH install time	20 minutes	One whole install over SSH. A longer run is treated as wedged and fails.
Agent update deadline, default	10 minutes	A running agent update that the new agent has not confirmed by then is rolled back automatically.
Agent update history	20 attempts	The attempts a cluster's agent history lists, newest first.
Cluster allocation windows	1, 6 or 24 hours	The windows the allocation chart accepts.

Observability and retentionCopy Anchor Link

Limits on logs and metrics and on how long telemetry is kept.

Limit	Value	Applies to
Telemetry retention	7 UTC days	Container logs, pod metrics, traffic samples and canvas metric samples. Older data is dropped hourly.
Cluster allocation retention	7 days	The samples behind the cluster allocation chart.
Service metrics window	1h, 6h or 24h; 1h, 24h or 7d for the summary	The window of the resource and traffic metrics takes 1h, 6h or 24h. The window of the metrics summary behind the console Metrics tab takes 1h, 24h or 7d. Any other value answers 422. The default is 1 hour.
Canvas metrics window	30 minutes	Fixed. The canvas card shows up to 30 points in 60-second buckets.
Canvas cron history	At most 7 runs	The runs a cron card lists, newest first.
Canvas Postgres status age	2 minutes	After 2 minutes without a report, the card shows no instance markers.
Cluster events in the runtime view	50	The most recent cluster events a service's runtime view returns.
Log shipping rate	2,000 lines per second per agent	Across all pods of one cluster. Lines over the rate are dropped and counted.
Container log line	At most 8 KiB	A longer line is truncated.
Log batch body	At most 8 MiB	The body of one log batch from an agent. This is the one request body limit above 1 MiB.
Agent event batch	At most 200 events	A batch with more events answers 422.
Service Logs tab buffer	5,000 lines	The console keeps the newest 5,000 lines of the service Logs tab.
Log viewer buffer	10,000 lines	The console keeps the newest 10,000 lines of the environment logs panel. The deployment detail card loads at most the first 5,000 lines of a build log (5 pages of 1,000) and, for runtime output, the latest 200 retained lines plus at most 1,000 live lines.

NotificationsCopy Anchor Link

Limits on notifications and their channels.

Limit	Value	Applies to
Channel label	1 to 100 bytes	The label with surrounding whitespace trimmed. A label outside the range answers 422.
Delivery attempts	At most 24	After 24 failed attempts the channel gives up on that notification. A refusal that retrying cannot fix, such as an HTTP 4xx other than 408 or 429 or a host that resolves only to private addresses, gives up on the first attempt.
Retry delay	30 seconds, doubling to at most 1 hour	The wait after each failed delivery.
Delivery time	10 seconds	One send to a channel. A slower response counts as a failed attempt.
Slack message text	At most 3,000 bytes	The text of a section block, title and body together. Longer text is truncated and ends in ….
PagerDuty summary	At most 1,024 bytes	The summary, which is the notification title. A longer summary is truncated and ends in ….

Git connectionsCopy Anchor Link

Limits on an organization's git connections.

Limit	Value	Applies to
Connection label	1 to 20 bytes	A label outside the range, or one that starts with GitHub or Gist in any case, answers 422. A label already used in the organization answers 409.
Webhook body	At most 1 MiB	A larger webhook delivery is refused.

Organizations and accessCopy Anchor Link

Limits on organizations, members and teams and API tokens.

Limit	Value	Applies to
Organization slug	1 to 63 characters	Lowercase letters and digits in single-hyphen-separated segments. A slug outside the shape answers 422.
Invitation lifetime	7 days	An invitation that is not accepted expires. Accepting it afterwards answers 409.
Browser session	30 days	A session ends 30 days after sign-in, however active it is.
Sign-in flow	10 minutes	The time between starting a sign-in and its callback.
API token lifetime	1 day or more	lifetimeDays. A value below 1 answers 422. A token created without it never expires.
API token project list	At least 1 project	A token limited to projects must name at least one. An empty list answers 422. Omit the list for a token that reaches every project.

UpdatesCopy Anchor Link

Limits on updates of the control plane and the cluster agents.

Limit	Value	Applies to
Automatic update check	Every 6 hours	The control plane checks the release feed and the K3s channel feed.
Forced update check	Once every 30 seconds	A check requested within 30 seconds of the last one returns the last result without a new lookup.
Updater online window	2 minutes	The console offers an update only if the updater polled within this time.
Update with no updater poll	15 minutes	A running update with no updater poll for this long is marked failed.
Update history	10 updates	The finished control plane updates the console lists.