zrok Documentation

How Tos Agent Windows Service Index (`website/docs/how-tos/agent/windows-service/index.mdx`) Copy Section

sidebar_label: Set up the Windows agent service Copy Chapter

Set up the Windows agent service

Run the zrok agent as a Windows service so it starts automatically with your system. Service management is handled
through nssm (Non-Sucking Service Manager), a third-party utility. Review the nssm
documentation before proceeding.

Prerequisites Copy Chapter

• A zrok account token.

• zrok2.exe and nssm.exe installed in a protected location. This guide uses C:\Program Files\zrok2\.

• A Command Prompt open in C:\Program Files\zrok2\:

  cmd Copy

  cd "\Program Files\zrok2"

Enable the service environment Copy Chapter

The Windows service runs as the Local System user, whose home directory is C:\Windows\System32\config\systemprofile.
You need to enable a zrok environment there.

1. Set USERPROFILE to the Local System home directory:

   cmd Copy

   C:\Program Files\zrok2>set USERPROFILE=c:\Windows\System32\config\systemprofile

2. Enable a zrok environment for the service:

   cmd Copy

   C:\Program Files\zrok2>zrok2 enable <accountToken>

Install the service Copy Chapter

1. Run nssm install to open the configuration dialog:

   cmd Copy

   C:\Program Files\zrok2>nssm install zrokAgent

   Windows may prompt for elevated Administrator privileges before showing the nssm installation dialog.

2. On the Application tab, configure the following fields:

   • Path: C:\Program Files\zrok2\zrok2.exe
   • Startup directory: C:\Windows\System32\config\systemprofile
   • Arguments: agent start
   • Service name: zrokAgent

3. Click the I/O tab and configure log output:

   • Output (stdout): C:\Windows\System32\config\systemprofile\.zrok2\agent-stdout.log
   • Error (stderr): C:\Windows\System32\config\systemprofile\.zrok2\agent-stderr.log

   Setting up I/O redirection produces logs from the zrok2 agent start process that are useful for troubleshooting.
   Optionally, configure log rotation on the File rotation tab if your setup requires it:

4. Click Install service.

5. Open the Windows Services utility. You should see the new zrokAgent service:

6. Start the service by clicking the start button in the toolbar, or right-clicking the service and selecting Start:

7. Verify the service is working by opening a Windows Explorer window at
   C:\Windows\System32\config\systemprofile\.zrok2. You should see the log files and the agent.socket file used by
   the zrok CLI:

8. Open the agent console:

   cmd Copy

   C:\Program Files\zrok2>zrok2 agent console

   This opens a web interface for managing the agent. You can create shares and accesses from the console, or continue
   using the zrok CLI.

:::note
Whenever you interact with this service environment from a Command Prompt, set USERPROFILE to
C:\Windows\System32\config\systemprofile first. Otherwise, zrok commands will use your default user profile directory
instead.
:::

Non-interactive service installation Copy Chapter

nssm supports a command-line interface that bypasses the GUI. Run these commands from an Administrator Command Prompt:

1. Create the service:

   cmd Copy

   C:\Program Files\zrok2>nssm install zrokAgent "C:\Program Files\zrok2\zrok2.exe" agent start

2. Set the working directory:

   cmd Copy

   C:\Program Files\zrok2>nssm set zrokAgent AppDirectory C:\Windows\System32\config\systemprofile

3. Configure log output:

   cmd Copy

   C:\Program Files\zrok2>nssm set zrokAgent AppStdout C:\Windows\System32\config\systemprofile\.zrok2\agent-stdout.log

   cmd Copy

   C:\Program Files\zrok2>nssm set zrokAgent AppStderr C:\Windows\System32\config\systemprofile\.zrok2\agent-stderr.log

4. Start the service:

   cmd Copy

   C:\Program Files\zrok2>sc start zrokAgent

Remove the zrok agent service Copy Chapter

Run the following commands from an Administrator Command Prompt:

1. Stop the service:

   cmd Copy

   C:\>sc stop zrokAgent

2. Delete the service:

   cmd Copy

   C:\>sc delete zrokAgent

3. With USERPROFILE set to C:\Windows\System32\config\systemprofile, remove the zrok environment from your system
   and from the zrok service:

   cmd Copy

   C:\Program Files\zrok2>zrok2 disable

Current Bandwidth Limit Relax (`docs/current/bandwidth-limit-relax.md`) Copy Section

Bandwidth-limit relaxation

The controller checks limited accounts after their bandwidth usage drops below the configured threshold. It restores each share's dial policies and removes the account's bandwidth-limit journal entry only when every applicable share succeeds. Failed accounts retain their entries for a later cycle, while other accounts continue. Policy lookup by deterministic name makes a partial retry safe, and a second cycle over restored policies creates nothing.

The cycle uses one database transaction. A store error ends the cycle because PostgreSQL aborts the transaction after a failed statement.

Which dial policies a share should have Copy Chapter

controller/limits/dialPolicies.go computes a share's desired dial policies separately from ensuring them; relax and the repair command share it.

• Public share frontend policy, <envZId>-<shrZId>-dial, tagged with the share token. Its identity roles are the frontends of every namespace the share's live name mappings point at (mapping, name and namespace all undeleted), de-duplicated, which is how allocatePublicResources creates it. frontend_selection is the v1 column and v2 never writes it, so it is used only for a v1-created row with no live mappings. A share with neither, or whose namespaces have no frontends, has no frontend policy; its create made none, and relax counts it as done.
• Private access policy, <frontendToken>-<envZId>-<shrZId>-dial, one per frontend row with private_share_id. access private does not check the share mode, so these exist for public shares too, and relax restores them for both modes.

Influx deadline Copy Chapter

Each limits-agent Influx query is bounded by limits.query_timeout (default 30s) and by the agent's context, which Stop cancels. A query that times out or fails part-way through its result is an error, never zero usage, so it cannot relax an account.

Repairing shares the journal no longer reaches Copy Chapter

Incidents cleared by hand, and cycles that crashed before step 1, left live shares with no dial policy and no journal entry; relax never visits them. zrok2 admin repair-dial-policies <configPath> walks every live share, computes its desired dial policies and reports each one missing by account, share token and policy name. It honours the journal: an account with a global limit entry, or a limit entry whose limit class has no backend mode, is skipped as a whole; a limit entry whose class has a backend mode skips that mode's shares. It never deletes.

Production procedure:

1. Run zrok2 admin repair-dial-policies <configPath> (a dry run) and review the missing policies and skipped accounts.
2. Run it again with --apply. It creates the missing policies through the same find-then-create as relax, continues past individual OpenZiti failures, lists under failed shares any v1-created share whose selected frontend no longer exists (with the frontend it selects), and prints checked, missing, created and failed counts; any failure exits non-zero after the run.
3. Run the dry run again; it should report nothing missing.

Current Dynamic Proxy Mappings (`docs/current/dynamic-proxy-mappings.md`) Copy Section

Dynamic proxy mappings

The dynamic frontend (zrok2 access dynamicProxy, endpoints/dynamicProxy/) serves requests from an in-memory map of hostname to share token. The controller's frontend_mappings rows are authoritative; the map learns them three ways, all applied by one loop in mappings.go:

The delta pull never removes a name, by design, and stays that way; removals are the subscriber's job and, when an update is lost, the reconciliation's.

Start Copy Chapter

The initial full pull retries with backoff, one second doubling to thirty, until it succeeds or the frontend stops, logging each failure. Until it succeeds the map is empty and requests answer not-found.

Reconciliation Copy Chapter

On each tick the frontend pulls the complete set and, under the map's lock, makes the map match it:

• a name absent from the set is dropped;
• a name missing from the map is added;
• a name whose share token or id differs from the set's is replaced with the set's row;
• a name whose row is identical is left alone.

Each difference is logged at info with the name and both tokens, and one summary line gives the counts and elapsed time. A failed pull is logged at error and the map is left untouched.

A complete set that comes back empty while the map is non-empty is logged at warn and not applied the first time. For a frontend carrying traffic a single empty answer is more likely a failure the client did not see than a world with no shares, and applying it would drop every mapping at once. If the very next reconciliation is also empty it is applied like any other set, each drop and the summary logged as usual, so a frontend whose last mappings really were removed stops serving them within two intervals. A non-empty set or a failed pull in between resets the count.

Subscriber acknowledgement Copy Chapter

The subscriber consumes its own queue, exclusive and deleted with the process, with manual acknowledgement and a prefetch of amqp_subscriber.prefetch (default 64).

Nothing requeues. The queue has no other consumer and dies with the process, so a requeued message can only return to the same handler, and one it cannot process would return forever. A message lost with the queue is what reconciliation recovers.

Current Garbage Collection (`docs/current/garbage-collection.md`) Copy Section

Garbage collection

zrok2 admin gc <configPath> [--delete] [--min-age 24h] (cmd/zrok2/adminGc.go, controller/gc.go) runs as its own process against the controller's store and OpenZiti controller, and removes OpenZiti objects left behind by shares that no longer exist. It opens the store with auto-migration off (controller/adminStore.go), so even a dry run never changes the schema; migrations belong to the controller and zrok2 admin migrate.

What gc owns Copy Chapter

gc examines services, configs, service policies and service edge router policies tagged zrok. An object belongs to a share when it carries a zrokShareToken tag:

• token belongs to a live (not deleted) row in shares: live, kept;
• token belongs to no live row: orphaned, a candidate;
• no zrokShareToken tag: not share-owned, never touched.

Names are never consulted. The last group covers agent-remote objects (zrokAgentRemote), frontend identities and their policies, the dynamic proxy controller's service, and anything else carrying only the zrok tag. An access-path dial policy carries the share token as well as zrokFrontendToken, so it follows its share. Identities and edge router policies belong to environments and are handled by disable, not gc. Live shares come from the shared shares table, so the v1 line's shares count as live too.

Age guard Copy Chapter

A candidate whose createdAt is younger than --min-age (default 24 hours) is skipped and counted as too young. A share create allocates its OpenZiti objects before its row commits, so for the length of that request its objects look orphaned; the guard keeps gc off them, and a later run picks up a real orphan. The store is read before OpenZiti is listed, so an object created after the read is younger than the run.

The default is a day rather than minutes for two reasons. createdAt is stamped by the OpenZiti controller's clock and compared against the clock of the host running gc, and a day is well clear of any skew between the two. And since v2.0.6 stopped the leak, the orphans left to reclaim are old; nothing younger than a day needs collecting, so the longer guard costs nothing. A shorter --min-age is for a deliberate cleanup, such as on a dev environment, where the clocks are known to agree.

Modes Copy Chapter

Every kind is listed in full, 500 at a time with an advancing offset (automation.FindAll). The report goes to stdout in both modes: for each kind the counts of live, orphaned, too young and not share-owned objects, then the orphans' ids and names grouped by share token. The JSON log names every orphan and too-young object.

Without --delete it is a dry run and nothing is deleted. With --delete the orphans are deleted by id in the order service edge router policies, service policies, configs, services, so a service is never left referenced by a policy or config that outlives it. An object already gone counts as collected; any other failure is logged and the run continues, and the command exits with an error naming the number of failed deletes. A table of deleted, already gone and failed counts per kind follows the report.

Production procedure Copy Chapter

1. Run the dry run and keep its output.
2. Review it: every live share's objects should be counted live, the orphans listed by token should be shares you expect to be gone, and nothing without a share token appears in the orphan list.
3. Run with --delete. Objects created since the dry run are either live or too young.
4. Run the dry run again; it should report no orphans.

Current Metrics Consumer (`docs/current/metrics-consumer.md`) Copy Section

Metrics consumer bounds

The controller consumes metrics with manual acknowledgement and a finite prefetch window. It nacks malformed JSON and unusable events without requeue immediately. A usable event has namespace fabric.usage, a numeric interval_start_utc, a string tags.serviceId, and a usage object. A missing circuit_id produces a warning and remains acceptable.

Within usage, a present ingress.tx, ingress.rx, egress.tx, or egress.rx must be numeric; a mistyped counter makes the event invalid. Absent counters remain zero, so intervals containing only ingress or only egress are accepted.

The agent holds the Influx writer as its explicit durable sink. It retries that sink locally with exponential backoff, then nacks without requeue if the attempt or elapsed-time budget runs out. Remaining sinks do not receive an event whose durable write failed. Once the durable sink succeeds, later sinks run without retries; their errors are logged and the delivery is acknowledged.

A panic during per-message processing is logged at error level with the recovered value and up to the first 512 bytes of the message body. The delivery is nacked without requeue and processing continues with the next message, preventing a poison message from repeatedly crashing the controller. Legacy sink calls carry their panics back from the guarded goroutine to this recovery boundary. The shutdown drain remains outside it and leaves deliveries unsettled.

The limits sink runs after Influx. If its queue stays full, it logs and counts the dropped handoff, then returns success so the delivery is acknowledged. The usage remains in Influx for later enforcement. DroppedEvents() exposes the limits handoff drop count.

The following optional configuration values use these defaults when unset:

Share-detail enrichment and the durable write share one per-message deadline, including waiting for a store connection. Enrichment has three outcomes:

• A confirmed missing share is recognized as errNotAShare, debug-logged, and processing continues without retries or attribution. This is legitimate traffic for another service; the Influx writer skips events without a share token and the delivery is acknowledged.
• A share is attributed and processing continues to the durable sink. Ephemeral environments deliberately have no account: enrichment reports that condition at debug level, retains the share token and environment ID, and continues with account ID zero without retries.
• A store failure is retried with the configured attempts and backoff within the shared deadline. Exhaustion is logged and nacked without requeue, and no sinks run. Treating an unavailable store as proof that the service is unrelated would silently lose real share usage.

The consumer cancels database lookups, active writes, and retry waits at shutdown. It drains events so a source blocked on send can exit, leaving drained deliveries unsettled. A delivery held by the source when its send is cancelled is also left unsettled, as is an active delivery interrupted before durable success. Closing the AMQP connection lets the broker requeue these deliveries for recovery. This differs from failed processing: shutdown is not a processing failure, and nacking these valid messages would discard them on restart.

The built-in sinks accept cancellation through HandleContext while preserving the existing UsageSink.Handle interface. A sink implementing only Handle runs through a single guarded call slot: if it never returns, subsequent calls time out without starting more goroutines.

No failed-processing path requests requeue. A broker policy may route discarded deliveries to a dead-letter queue with its own length and TTL bounds; no such policy is required or configured by the controller. The limits agent's own Influx queries are bounded separately, by limits.query_timeout and the agent's shutdown (see bandwidth-limit-relax.md). A stuck limits query cannot block this consumer beyond its bounded handoff.

Current Repair Store (`docs/current/repair-store.md`) Copy Section

Store repair

zrok2 admin repair-store <configPath> [--apply] [--batch 500] (cmd/zrok2/adminRepairStore.go, controller/repairStore.go) runs as its own process against the controller's store and releases the store rows a teardown would have released had it run: rows left by shares deleted before teardownShare released names on every path, and by teardowns that never ran or stopped part-way. It opens the store with auto-migration off, as admin gc and admin repair-dial-policies do (controller/adminStore.go): a store behind the binary's schema fails the command rather than being migrated by it. healSeveredName repairs a name when someone asks for it (see share-teardown.md); this sweep reaches the rest, which no request will ever visit.

What it repairs Copy Chapter

Each condition is one a teardown would have handled had it run. They run in this order.

• A. A live environment of a deleted account, and a live share in a deleted environment (or in a live environment of a deleted account, which A is about to delete). The environment goes through removeEnvironmentFromStore, the store half of disable: its own frontends and the environment row are soft-deleted. The share goes through releaseShareFromStore, the store half of teardownShare: its name mappings and allocated names, frontend mappings, access frontends, access grants and the share row. Environments go first, a batch of environments at a time, then shares. This is store-side only. It makes no OpenZiti calls: once the share row is deleted its token is no longer live, and the next admin gc run collects its objects.
• B. A live access frontend (frontends.private_share_id set) whose share has no live row. Soft-deleted. Shares torn down before step 13 left these, because teardownShare removed their dial policies but not the rows.
• C. A live name of a deleted account. Soft-deleted, with any live mapping on it soft-deleted first. Account deletes before step 13 left these.
• D. A live auto-allocated name that no live mapping holds. Soft-deleted.

Then the mapping conditions:

1. A live share_name_mappings row whose share has no live row. The mapping is soft-deleted; if its name is auto-allocated (not reserved) and still live, the name is soft-deleted too, as teardownShare does. Reserved names survive. A mapping whose name is also deleted counts here, not under 2.
2. A live share_name_mappings row of a live share whose name is deleted. The availability check looks mappings up by the live name's id, so it never sees these. Soft-deleted.
3. A frontend_mappings row whose share token belongs to no live share: the share is deleted, or no share row carries the token at all. The availability check treats the second kind as a live holder and never heals it; only this sweep removes it. Deleted; the table has no deleted column.

A row can match more than one condition when the survey runs: an allocated name of a deleted account held by a stranded share is counted under A's shares and under C. The earlier condition repairs it, and the later one finds it already done, so its repaired count is lower than its found count. The survey's found counts are therefore not additive.

A share token is unique only among live shares, so condition 3 asks whether any live share carries the token, not whether a row with the token is deleted.

Modes Copy Chapter

Without --apply it is a dry run. One transaction, rolled back, counts each condition (A split into environments and shares, 1 into reserved and auto-allocated), counts the auto-allocated names condition 1 would release, and lists up to twenty rows of each: the row's table and id, then whichever it has of name, namespace token (frontend token for condition 3 and B, OpenZiti id for an environment), share token, and the environment or account it belongs to, marking a frontend mapping whose token has no share row. The report goes to stdout and the totals to the log.

With --apply the survey is printed and then each condition is repaired in order: A environments, A shares, B, C, D, 1 reserved, 1 auto-allocated, 2, 3. A goes first because a released share takes its name mappings, frontend mappings and access frontends with it. Among the mapping conditions, reserved names go first so the names users chose are freed first if a run is interrupted. Each batch is its own transaction: a plain select ... order by id limit N of the matching rows, then an update or delete by those ids, in SQL both engines accept. Progress is logged after each batch. A failed batch rolls back, is reported, and stops the run with a non-zero exit; the batches before it stay committed. Repaired rows no longer match, so a re-run resumes where the last one stopped. The report ends with found and repaired per condition, the names condition 1 released, batches run and failed batches.

No notifications Copy Chapter

The command touches the store only. It publishes no unbinds: dynamic frontends drop the removed frontend mappings at their next periodic reconciliation (dynamic-proxy-mappings.md). It runs outside the controller, which owns the publisher, and a frontend mapping it removes serves no live share, so nothing is lost while the frontend waits.

What is left in OpenZiti Copy Chapter

The command makes no OpenZiti calls; it is store-side by decision. The OpenZiti side of the same debt is admin gc's (garbage-collection.md), and that covers the objects of shares released under A: once the share row is deleted its token is no longer live, and the next gc run collects them.

gc does not cover environments. The identity and edge router policy of an environment soft-deleted under A stay in OpenZiti. After condition A, the apply report lists those identities' ids under a heading saying they are left in OpenZiti, for removal one at a time with zrok2 admin delete identity <zId>, which deletes the edge router policy named after the identity and then the identity. Only environments in committed batches are listed. The dial policies of the frontends in those environments are tagged with share tokens that may still be live, so gc keeps them; they also stay.

Production procedure Copy Chapter

1. Run the dry run and keep its output.
2. Review the sample. Live shares are expected under "shares in deleted environments", whose environments are gone, and under "mappings to deleted names", whose names are gone. Under every other condition each share token should be a share you expect to be gone, and no live share should appear. Under "allocated names with no mapping", check that the names are not ones their owners un-reserved on purpose (see below).
3. Run with --apply. Rows severed since the dry run, if any, are repaired too; the counts are the dry run's, the repaired column is what was done.
4. Run the dry run again; it should find nothing.
5. Remove the identities the apply report listed as left in OpenZiti, with zrok2 admin delete identity <zId>, then run admin gc to collect the released shares' objects.

Unmapped allocated names Copy Chapter

updateShareName lets an owner set reserved to false on a name no share holds. That leaves a live, auto-allocated name with no mapping, which is exactly condition D. A run of the sweep releases such a name, as the owner's next teardown of a share on it would. The production snapshot had three, which may be this path rather than a leak.

Current Share Teardown (`docs/current/share-teardown.md`) Copy Section

Share teardown

teardownShare (controller/teardownShare.go) tears a share down. unshare, disable and admin deleteAccount (through disableEnvironment) all call it, once per share, inside the request's transaction. Its store half is releaseShareFromStore, the only code that deletes a share row; admin repair-store calls that half alone for shares stranded in deleted environments (see repair-store.md). It runs, in order:

1. Name mappings: the share's live share_name_mappings rows are soft-deleted, and each auto-allocated (non-reserved) name they point at is soft-deleted with them. Reserved names survive and can be used by the next share.
2. Frontend mappings: every frontend_mappings row carrying the share token is deleted, whether or not a dynamic proxy controller is configured. One unbind update is returned per row.
3. Access frontends: every live frontends row whose private_share_id is the share, the private accesses to it, is soft-deleted. Their dial policies carry the share token and go in step 6. unaccess still removes a single access on its own.
4. Access grants for the share.
5. The share row.
6. OpenZiti objects tagged zrokShareToken=<token>. An object already gone counts as deleted; any other failure fails the teardown.

Any failure returns at once and the caller's transaction rolls back, leaving every row for a retry. OpenZiti goes last so that an OpenZiti failure leaves the store untouched.

Frontend mapping updates, binds from share create and unbinds from teardown, are returned to the handler and published only after its trx.Commit() returns nil, through publishMappingUpdates. A failed publish is logged at error level and not returned: the committed rows are authoritative. A lost bind or unbind is recovered by the dynamic frontend's periodic full reconciliation; see dynamic-proxy-mappings.md. Without a dynamic proxy controller the rows are still written and nothing is published.

Account delete Copy Chapter

Admin deleteAccount disables each of the account's environments, which tears down every share in them, and then, before it deletes the account row, releases the account's names (releaseAccountNames): every live name of the account, reserved or not, is soft-deleted. By then no live share of the account can hold one. A mapping on one of its names to a live share (some other account's share) is a store error and fails the delete, rolling everything back; a severed mapping, to a share already deleted, is soft-deleted with its name.

Share create Copy Chapter

On share create, a failed frontend_mappings insert fails the request; the share-create compensation then removes the OpenZiti objects the request created.

Name availability Copy Chapter

A name whose share has been deleted can still carry a live share_name_mappings row, or a frontend_mappings row, written before teardownShare released names on every path. healSeveredName (controller/healSeveredName.go) is the one availability check for a name; share create (for a user-specified name), createShareName and deleteShareName all call it, inside the request's transaction. It reads the name's live mappings with their share state, and the name's frontend mappings on the namespace's dynamic frontends:

• Any mapping whose share is live, or a frontend mapping with no share row at all, is a conflict carrying the holder's token. Nothing is modified, and the handler answers 409 name '<name>' in namespace '<ns>' is in use by share '<token>'; run 'zrok2 delete share <token>' to release it.
• Otherwise every mapping is dead: each share name mapping is soft-deleted, each frontend mapping is removed, and each is logged at info with the dead share's token. The request then proceeds as if the name had been free.

Each frontend mapping removed yields an unbind, returned like teardownShare's and published only after the handler's commit: createShareName and deleteShareName publish them on their own, and share create puts them ahead of its binds in the one list it publishes, so a frontend sees the unbind and then the bind for the same name. In share create, a conflict (a namespace or name that does not exist, a name the account does not own, a namespace it is not granted, a live holder) is a nameSelectionConflict and answers 409; any other error from the name check, a store failure in the heal included, answers 500.

The healing commits or rolls back with the request; a request that fails later leaves the severed rows for the next attempt to heal again. It is a repair of past damage, not a teardown path: it touches no share row and no OpenZiti object. The auto-allocated branch of share create (no name given) creates a fresh name and does not call it.

Current Ziti Session (`docs/current/ziti-session.md`) Copy Section

Controller OpenZiti management session

The controller shares one OpenZiti management client per API endpoint and username for the life of the process, including bandwidth-limit enforcement and relaxation. It fetches the controller CA bundle and authenticates when that client is first created. A plain http:// endpoint has no TLS, so the CA fetch is skipped for it; this is what lets controller tests reach a fake Ziti through the production client. A failed initial build is not cached; the next call tries again.

When a management request receives HTTP 401, the transport refreshes the session and replays the request once, including its body. Concurrent requests share one in-flight refresh; no lock is held across the authentication call. The CA bundle and management transport remain in use across refreshes. Failed re-authentication or a second 401 returns the operation's typed unauthorized error to its caller; there is no retry loop.

A failed refresh is remembered for five seconds: requests still holding the failed session during that window get the unauthorized error immediately, and the first request after it makes one fresh attempt. A persistent authentication failure therefore costs one login per window and fails operations quickly instead of serializing them. The first build of the client for an endpoint and username happens outside the cache lock; concurrent callers for the same key wait for that build and share its result, and callers for other keys are not blocked.

The process-wide zrok.ziti.authentications expvar counter counts successful authentications. Read it at /debug/vars on the configured admin.profile_endpoint listener. Each successful authentication also writes an INFO log with the running count and reason (initial or expired). After startup the count should remain stable across ordinary share creates and deletes, increasing only when an expired session needs replacement.

When an OpenZiti rate limiter answers a management request with HTTP 429, the transport consumes the response and returns *automation.RateLimitedError, naming the limiter (the error code in Ziti's envelope, SERVER_TOO_MANY_REQUESTS for the command rate limiter), the method and the path. A 429 from /authenticate during a refresh is returned the same way with limiter authenticate, and is remembered for the failed-refresh window like any other refresh failure; requests waiting on that refresh receive the rate-limited error rather than their typed 401. Nothing is retried. automation.IsRateLimited recognises the error through any wrapping. The share, unshare, access, unaccess, enable and disable handlers answer it with 503 and Retry-After: 5; admin and agent handlers still answer 500.

Each 429 increments the process-wide zrok.ziti.rate_limited expvar counter, beside zrok.ziti.authentications at /debug/vars, and writes one WARN log line naming the limiter, method and path with the running count. The counter should stay at zero in ordinary operation; a rising count is the evidence for adding retry or a concurrency cap.

Credentials are retained from the first successful build for an endpoint and username. Restart the controller after changing credentials. Separate admin command processes have their own session.

Journal 2026 09 24 (`docs/journal/2026-09-24.md`) Copy Section

2026-09-24

• Retaining a limit journal entry requires every policy creation to be idempotent: earlier shares may have succeeded before another share failed, so the next cycle sees both again.
• A nil frontend_selection is normal for v2 public shares; it is not evidence of a corrupt row. Rebuilding the missing dial policy from name mappings remains separate work.
• Store errors still abort the shared relax transaction. PostgreSQL poisons a transaction after a failed statement, even though the sqlite tests continue from one.
• The zrok-one-ziti-session Terminus quality describes a later stage: NewZitiAutomation still authenticates per call. Step 1 deliberately leaves that production constructor unchanged; Terminus flags it, so this stage awaits the operator's disposition rather than a client-cache change.

Journal 2026 09 25 (`docs/journal/2026-09-25.md`) Copy Section

2026-09-25

• Terminus review of the relax-cycle stage (session 9d240f423f4a) returned five blocking findings, all in code the stage did not touch. Vetoed by the operator on the condition that each is addressed by a later stage: per-call authentication in NewZitiAutomation (zrok-one-ziti-session), no ID-based compensation in the share handler and DeleteWithFilter stopping on not-found (zrok-compensate-by-id, zrok-absence-is-success), bind/unbind published inside the transaction (zrok-notify-after-commit), and the swallowed bind error in processDynamicMappings (zrok-store-engine-parity). Each has a stage in the route; none is to be fixed opportunistically inside an unrelated stage.
• The reviewer reports pre-existing debt in untouched code as findings against the change under review. Expect the same vetoes to recur on later stages until those stages land; no rubric change was made.
• The relax-cycle change was exercised against a real Ziti controller and a PostgreSQL store (local dev environment, etc/dev.yml with the secrets block removed): two limited accounts, one holding a public share with NULL frontend_selection. Over six 15-second cycles the account with the public share was retried every cycle with its journal entry retained and the public share named in the log, its private share's dial policy was recreated exactly once, the other account was relaxed and cleared on the first cycle, and the controller stayed up. The fake and the real controller agreed on the list-by-name lookup the idempotency check depends on.
• ZROK2_API_ENDPOINT does not override an enabled environment's stored endpoint (env_v0_4/api.go, ApiEndpoint()): the env wins. Client and admin commands for a local controller need a HOME whose ~/.zrok2 is not enabled elsewhere.
• Observed in passing: zrok2 access private that fails to bind its local port runs unaccess on the way out, which removes the frontend row but left the Ziti dial policy behind. Same family as the create-path compensation work; not fixed here.
• Before/after on the same live setup: the controller built from the committed HEAD (no nil guard) panicked 12 seconds after a limit journal row was inserted for an account holding a public share with NULL frontend_selection, with the stack relaxPublicShare → relaxAction.HandleAccount → Agent.relax. The working-tree controller on the identical rows logged the share, retained the entry, and stayed up. A limited account cannot create shares (CanCreateShare refuses), so a reproduction has to create the share before inserting the journal row.
• Metrics failures never requeue: AMQP redelivery carries no incremented retry count and a persistent sink failure becomes a hot loop. Retries stay local and bounded. Influx exhaustion nacks without requeue; a limits handoff drop returns nil and acks because Influx already holds the usage used by later enforcement.
• Optional bounded replay belongs in a broker dead-letter policy, not QueueDeclare arguments: the durable queue's arguments cannot be changed in place. The consumer neither installs nor requires a DLX.

Journal 2026 09 26 (`docs/journal/2026-09-26.md`) Copy Section

2026-09-26

• Round 4 supersedes the blanket best-effort enrichment disposition: confirmed not-found continues without retry (normal traffic for another service), while transient store errors retry then drop because acknowledging without attribution silently loses real share usage. Enrichment and durable writes now share one per-message deadline.
• Shutdown is not failed processing. Both the agent's drain and the source's cancelled send deliberately leave deliveries unsettled so the broker requeues them on connection close. The operator rejected Terminus's proposed shutdown nack because it would discard valid messages on restarts; the no-requeue rule applies to processing failures.
• Deadlines for controller/limits/influxReader.go are explicitly deferred by the operator to the relax stage. A stuck query can stall that worker, but the bounded handoff prevents it from parking the metrics consumer.
• Usage counters distinguish absent from mistyped: absent is zero for legitimate one-sided intervals; present-and-mistyped makes the event invalid.
• Operator vetoes for this stage: the bridge acknowledging a failed publish belongs on the route's filler track (publisher-side under-count, unable to fill the broker); environment disable bypassing shared share teardown belongs to a numbered later stage. Leave bridge.go, amqpSink.go, and disable.go untouched here.
• Ephemeral environments intentionally have a null account ID (migration 002); enrichment tolerates it, retaining share/environment attribution with account zero.
• The consumer isolates panics per message and drops the poison delivery without requeue, for the same reason as the relax cycle's isolation: one bad item must not crash controllers repeatedly through broker redelivery.
• Metrics consumer verified live against the dev RabbitMQ (Docker, rabbitmqctl inside the container) with InfluxDB pointed at a closed port and 300 synthetic fabric.usage events for a real share id. Pre-fix build: all 300 delivered and parked unacknowledged, messages_ready 0, none settled until the channel closed. Step 2 build (retry budget shortened to 5s for the run): messages_unacknowledged pinned at the prefetch of 64 throughout, ready draining as each message exhausted its budget and was nacked, all 300 dropped in about a minute, no panics, controller up. With Influx reachable, 100 events were acked and written within 5 seconds. Watch messages_unacknowledged; messages_ready reads 0 in the failure mode.
• A make test run does not refresh GOBIN; a live run of a working-tree change needs go build (or make) first, or it runs the previous install.
• Transient enrichment verified live: with a TCP relay between the controller and Postgres killed mid-run, events for a real share went through the bounded retry ("usage processing attempt '1' failed: ... connection refused") and were nacked without requeue ("message dropped"); with the relay restored the next events were enriched, written and acked; the controller stayed up throughout. The store's error through a dead relay is "connection refused" from BeginContext, never sql.ErrNoRows, so the not-found sentinel cannot misfire on an outage.
• zrok2 --verbose does not enable debug logging: PersistentPreRun in cmd/zrok2/main.go re-initialises dl at slog.LevelInfo when the flag is set. Pre-existing; not changed here.
• Ziti session refresh is guarded by generation rather than promising exact-once authentication: the goal is removing per-operation pressure on the shared authentication limiter, and occasional redundant refreshes are acceptable. The HTTP transport handles 401 so every manager and existing caller shares the same behavior, including replay of create bodies. Failed re-authentication or a persistent 401 propagates as the operation's typed error after at most one refresh/replay; it must never become a retry loop.

Journal 2026 09 27 (`docs/journal/2026-09-27.md`) Copy Section

2026-09-27

• Shared Ziti session verified live against a Ziti 1.5.4 controller. Step 2 build (per-call authentication): five share create/unshare pairs added ten admin API sessions on the Ziti side. Step 3 build: startup cost one authentication, ten create/unshare pairs added none, and after the controller's API session was deleted on the Ziti side the next operation succeeded with exactly one re-authentication logged reason 'expired' and no error. The counter at /debug/vars on the admin profile endpoint tracked both.
• The refresh replays a request once through http.Request.GetBody, which go-openapi's runtime sets for the buffered bodies it builds; a streaming body, or a refresh that itself fails, returns the original typed 401 to the caller. There is no retry loop behind a persistent 401.
• Ziti session refresh is single-flight rather than mutex-held (PR review of 63ff5ae5): holding the lock across /authenticate dedupes successes but serializes failures, since a failed refresh leaves the generation unchanged and each waiter then runs its own login. Under a sustained 401 (rotated or wrong credentials, disabled identity, Ziti itself up) that turned N concurrent handlers into a chain of N logins of up to 30 s, so the API looked dead rather than misconfigured. Now waiters share the in-flight attempt, and a failure is remembered for failedRefreshWindow (5 s) against the generation it failed for, so a persistent failure costs one login per window and everything else gets the typed 401 at once. The refresh runs on a context detached from the first caller's cancellation, so one abandoned request cannot fail or poison the window for the others. First build moved outside the cache lock for the same reason. The same change is owed on the v1 branch's controller/zrokEdgeSdk/session.go before v1.1.12.

Journal 2026 09 28 (`docs/journal/2026-09-28.md`) Copy Section

2026-09-28

• Share-create compensation deletes the objects the request recorded, by ID, and never calls CleanupByTag. checkPrivateShareTokenAvailability is a read before the create, so two requests for the same private token can both pass it; both carry the same zrokShareToken tag, and a tag-scoped cleanup by the loser would delete the winner's config, service and policies. Tag-scoped cleanup stays only where a share row already owns the token (unshare, disable, gc). controller/access.go has the same leak on its dial policy and is meant to reuse zitiCompensation.
• In real Ziti config names are unique too, so the private-token loser normally fails at the config create with nothing to compensate; the handler race test seeds the winner's service and policies without a config so the loser gets one object in before conflicting.
• automation.IsNotFound matches a fixed list of generated Delete*NotFound types: the pinned edge-api (v0.26.48) generates no Code() accessor, so there is no status to test. A new delete path in the package adds its type to the list, or its not-found will propagate as a failure.
• The generated edge-api errors format their payload as pointers (createServiceBadRequest &{Error:0x...}), so every manager call site wraps through wrapEdgeError, which unwraps the APIErrorEnvelope into ziti <code>: <message> (cause: ...) at the manager boundary. It wraps rather than replaces: IsNotFound and callers' errors.As match the generated type, so it has to stay in the chain. A new edge-api call in the package uses the helper, or its failures log without Ziti's message.
• The shadow analyzer is deliberately not in the vet gate: 163 findings tree-wide on main, nearly all the ordinary if err := f(); err != nil idiom. The share handler's lost allocation error is guarded by the restructure (no := of err inside the mode switch) and the handler tests.
• sessionCache.get skips the CA fetch for a plain http:// endpoint, which is what lets controller handler tests use zitifake through the production NewZitiAutomation. The session tests now run against a TLS fake (zitifake.NewTLSWithCredentials) so their CA-fetch assertions still cover the https path.

Journal 2026 09 29 (`docs/journal/2026-09-29.md`) Copy Section

2026-09-29

• Environment teardown (disableEnvironment, admin deleteIdentity) treats an already-deleted identity as deleted; anything else, a typed 401 included, still fails the request so the transaction rolls back and the rows survive for a retry. The identity is deleted by the ID the store records, so zitifake.SeedWithID exists to place one at an environment's ZId.
• The handler test for "other failures still fail" rejects every operation, so its 401 surfaces at the edge router policy listing before the identity delete is reached; the guard's own refusal of a 401 rests on automation.IsNotFound matching only the generated Delete*NotFound types.
• Share teardown is one routine, teardownShare; nothing else deletes a share row. A new share-deleting path calls it rather than composing store deletes, or it leaves names severed and frontend_mappings rows behind (the disable-path defect: a live mapping on a deleted share blocks the name forever through the unique index).
• Frontend mapping updates are returned as pendingMappingUpdate and published by the handler after commit, never from inside a transaction; the dynamic proxy controller no longer writes rows, only Publishes. A failed publish is logged and left to the frontends' reconciliation, not returned, since the rows are already committed. As of this step that reconciliation is only the frontend's higher-id pull, which recovers a lost bind but never a lost unbind; the unbind side is step 9's. Handlers publish through the mappingPub seam, set only when the dynamic proxy controller is configured; tests install a recording publisher whose store read times out while the publishing transaction is open (sqlite store has one connection), which is how "after commit" is asserted.
• Ziti cleanup is the last step of the teardown so a Ziti failure rolls back with the store intact. TestDisableOtherFailuresStillFail now meets its 401 at the share's CleanupByTag, before the edge router policy listing named above.
• removeFrontendsForEnvironment now fails the disable on a frontend policy delete failure instead of logging it, so no step of environment teardown logs and continues. A blanket RejectOperations cannot tell this apart from the later edge router policy failure (both answer 500), so TestDisableFrontendFailureRollsBack uses an environment with a frontend and no share and asserts the frontend's error in the log.
• The dynamic frontend's AMQP subscriber never requeues (step 9). Its queue is exclusive and auto-deleted per process, so requeue can only hand a message back to the same handler; a malformed one looped forever. Unparseable and unknown-operation messages are nacked without requeue, a full handoff channel still acks; a lost message is the reconciliation's to recover. Don't reintroduce requeue "for reliability".
• The full reconciliation holds back the first empty set over a non-empty map (one empty answer for a busy frontend is more likely an unseen failure, and applying it would black-hole the frontend) and applies the second consecutive one, so a frontend whose last mappings really were removed clears them within two intervals. A non-empty set or a failed pull in between resets the count (emptyPulls). Both halves are deliberate: the first empty set is not to be applied, and the second is not to be refused.
• The delta pull (refresh, id above the highest held) learns every row with a higher id, which includes a replacement (a name deleted and re-inserted gets a higher id), but never a deletion; that is by design and pinned by TestRefreshOnlyAdds. Removals come from unbinds and the reconciliation. mapping_reconcile_interval and mapping_refresh_interval are independent.
• The dynamic proxy subscriber dials like the metrics AMQP source: DialConfig with a net.Dialer.DialContext on the shutdown context, a context.AfterFunc that closes the socket on shutdown, and a 10s deadline on the handshake and again on queue setup. The AfterFunc is the part that matters for a broker that accepts and never answers; the dial context alone does not interrupt a handshake already under way. disconnect stops the AfterFunc so reconnects don't accumulate them.

Journal 2026 10 02 (`docs/journal/2026-10-02.md`) Copy Section

2026-10-02

• zrok2 admin gc decides ownership by the zrokShareToken tag and never by name. v2 policy names lead with the environment ZId (<envZId>-<shrZId>-bind, <envZId>-<token>-serp, <feToken>-<envZId>-<shrZId>-dial), so any name parsing marks every live share's policies orphaned; that is how the old gc stripped a live private share on dev. An object with no share token is not gc's (agent-remote, frontend, dynamic proxy controller objects) and is counted, never deleted.
• A ziti list with limit zero returns the default page of ten, not everything. automation.FindAll pages at MaxPageSize (500). GetByName and GetByID still send a zero limit, which is harmless for name and id lookups. The fake now pages the same way, so a test seeding more than ten objects of a kind and reading them through a zero-limit Find sees ten.
• DeleteWithFilter (and so CleanupByTag, the Ziti step of teardownShare) now lists through FindAll before deleting; before step 12 it read one page of ten, so a share with more than ten objects of one kind was torn down with the rest left behind. It must list everything first: deleting while paging by offset shifts later objects into pages already read.
• gc deletes policies and configs before services so that a failure part-way never leaves a policy or config pointing at a deleted service; a leftover service with no policies is harmless and the next run takes it.
• gc reads the live share set before listing Ziti, and the age guard is what covers a share whose objects exist before its row commits. Don't reorder the two reads or default --min-age to zero.
• Step 6 (relax for v2 public shares): frontend_selection is v1's column; v2 never writes it. A public share's desired dial policy comes from its live name mappings (namespace frontends), never from the share row; the row's selection is consulted only when there are no live mappings. Relax and admin repair-dial-policies share desiredDialPolicies, so a new policy kind added at create time needs adding there or both will miss it.
• admin repair-dial-policies must honour the bandwidth limit journal or it un-limits limited accounts: limitAction deletes dial policies and nothing else, so "missing dial policy" is exactly what a limited share looks like. It treats a limit entry whose limit class has no backend mode as whole-account limited, which is stricter than relaxAction's limitedBackends (that map ignores unscoped classes); deliberate.
• influxReader.runQueryForRxTx checks result.Err() after iterating. Without it, a deadline hit while reading the result ended Next() early and returned zero usage with no error, which relax reads as "under the limit".
• The relax fixture's "bad" share now fails through zitifake.RejectCreates on its dial policy name; a public share with no mappings and no selection now relaxes successfully, so it can no longer stand in for a failing share.
• A v1-shaped share whose frontend_selection names no live frontend is a per-share relax failure (missingPublicFrontendError, journal retained, cycle continues), not a store failure: a no-rows lookup aborts no PostgreSQL transaction, so ending the cycle for it stalled every account behind it. Any other lookup error stays a store failure. admin repair-dial-policies treats it the same way: the share is listed under failed shares with the frontend it selects, counted in failed (so the run exits non-zero), and the run continues; its access policies are not checked in that run, since the derivation stops at the error.
• Step 1a: a Ziti 429 is recognised in sessionTransport.RoundTrip by status code, not through the 75 generated *TooManyRequests types (the pinned edge-api has no status accessor); the authenticate 429 is the one generated type matched, because authentication bypasses the session transport. Don't add per-operation type checks.
• There is deliberately no retry or concurrency cap on a 429 (shelved: operations reported none since 2.0.5/2.0.6). zrok.ziti.rate_limited is what would reopen that; the handlers answer 503 with a fixed Retry-After: 5 instead.
• The 503 responders exist because specs/src/share.yml and environment.yml declare them; rest_server_zrok, rest_client_zrok, specs/zrok.yml and the sdk clients are outputs of bin/generate_rest.sh. The tree reproduces exactly with go-swagger v0.33.2 and openapi-generator-cli 7.14.0; v0.33.1 adds a header comment to every file, v0.34+ rewrite comment style and swag imports across ~450 files.
• enable now compensates like share and access: identity and edge router policy are recorded by id after each create and deleted unless the commit succeeds. Its enroll seam exists because Identities.Enroll performs a real enrollment against the JWT's issuer, which the fake cannot serve; tests replace it, so enrollment itself is untested here. The fake now accepts identity and edge router policy creates (it used to answer 405).
• newZitiCompensation takes a subject (compensatingShare, compensatingAccess, compensatingEnvironment) and a name for the log: the share token, the frontend token, the identity name. A new compensating path picks or adds a subject rather than reusing "share".
• bin/generate_rest.sh refuses to run unless swagger is v0.33.2 and openapi-generator-cli is 7.14.0; anything else rewrites hundreds of generated files the spec change didn't touch. With no Java, a wrapper script named openapi-generator-cli that runs the openapitools/openapi-generator-cli:v7.14.0 image (with --user $(id -u):$(id -g) and the repo mounted at its own path) satisfies it.

Journal 2026 10 05 (`docs/journal/2026-10-05.md`) Copy Section

2026-10-05

• Step 11: the share-create availability check now ignores dead mappings, and that switch cannot be separated from soft-deleting them. share_name_mappings has a partial unique index on name_id where not deleted, so a check that merely skips dead rows lets the request reach the mapping insert and turns the old 409 into a 500. healSeveredName does both in one routine for share create, createShareName and deleteShareName; a new name path calls it rather than querying mappings itself.
• healSeveredName is a repair, not a teardown. It must not grow OpenZiti calls or share-row deletes; anything that removes a share goes through teardownShare. It checks everything before modifying anything, so a conflict leaves the rows as they were even without the rollback.
• A frontend mapping whose share token matches no share row at all counts as a live holder (inherited from the old healStaleFrontendMappings), not as severed. That is why TestShareFailedFrontendMappingInsertFailsRequest no longer seeds an other-token row to make the insert fail: the check now answers that row with a 409 before the insert. The test makes the insert fail with a sqlite trigger instead.
• createShareName creates the name before calling healSeveredName, so the routine always receives a real name row; the new name has no share mappings, so only the frontend half does anything there, and a conflict rolls the name back.
• The auto-allocated branch of processNameSelections (no name given) does no healing, deliberately: its name is the fresh share token, so nothing can be severed on it. Its only change is that the not-granted refusal is now a typed conflict.
• healSeveredName returns one unbind per frontend mapping it removes (frontend token and name, like teardownShare). Share create puts them ahead of its binds in the one post-commit list. That order is what keeps the new share mapped, because unbind is by name only on the frontend (endpoints/dynamicProxy/mappings.go). An unbind published after the bind for the same name drops the new share's mapping. The name handlers publish their unbinds after their own commit.
• processNameSelections returns *nameSelectionConflict for the user-caused cases and a plain error otherwise; the share handler answers 409 only for the typed one (errors.As) and 500 for the rest. No-rows on the namespace or name lookup counts as user-caused (a 409, as before); a new user-facing refusal in that function must use the typed conflict, or it turns into a 500.

Journal 2026 10 06 (`docs/journal/2026-10-06.md`) Copy Section

2026-10-06

• Step 13: the name repair is the admin repair-names command, never a startup migration. A migration runs unattended at controller start, as one unbatched transaction against production PostgreSQL, with no dry run to review first. The sweep needs a reviewed dry run and small batches, and it repairs past data rather than changing the schema, so it runs when operations choose.
• FindFrontendMappingByFrontendTokenAndNameWithShareState decides share state with exists over every share row carrying the token (live if any is live), not a left join. shares_token_idx is unique only where not deleted, and private shares take user-chosen tokens, so a deleted and a live row can share a token; the old join returned an arbitrary one, and healSeveredName could remove a live share's frontend mapping. Any new query that maps a share token to share state needs the same shape.
• The three admin repair commands open the store through openAdminStore, which forces DisableAutoMigration on a copy of the config. A dry run must not change the schema either, and an operator running a newer binary against production would otherwise migrate it as a side effect. There is no schema check: a command fails only when a query hits a missing table or column. repair-names fails at once on a pre-v2 store; gc reads only shares, so it can run to completion against a behind store, which is harmless since it changes no rows there.

Journal 2026 10 07 (`docs/journal/2026-10-07.md`) Copy Section

2026-10-07

• Step 13 return. The production snapshot survey found 41,982 severed name mappings and 43,834 stale frontend mappings (the existing conditions), plus 11,371 live access frontends of deleted shares, 235 live names of deleted accounts, 38 live shares in deleted environments, 47 live environments of deleted accounts, and 3 unmapped allocated names. repair-store gained conditions A to D for those, run before the mapping conditions.
• Condition A is store-side only and leaves OpenZiti to gc. It calls releaseShareFromStore, the store half split out of teardownShare, so there is still one teardown routine and no second copy in the sweep. Once the share row is deleted its token is no longer live, and gc collects the share's objects on its next run. Boundary: the sweep is store-side by decision, and gc covers the shares' objects. The operator vetoed terminus's blocking zrok-one-teardown-routine finding (use teardownShare in the sweep) on that basis, so don't reopen it. gc does not collect the environments' identities and edge router policies. The apply report lists those identities for zrok2 admin delete identity; they are a known remainder, not an oversight.
• releaseAccountNames fails the account delete only on a mapping to a live share. A severed mapping, to a share already deleted, is released with its name. Failing on any live mapping would have blocked deleting every account that still holds a severed name until repair-store runs.
• Condition D also matches a name its owner un-reserved through updateShareName while no share held it. The sweep releases those too; the 3 production rows may be that path rather than a leak.
• The command was renamed admin repair-names to admin repair-store (controller/repairStore.go) once it began deleting share and environment rows; the 2026-10-06 entry uses the old name. The report's condition names were kept.
• Small controller stage: a service policy's dial or bind type is read from the listed policy's Type (ServicePolicies.DeleteByTagAndType), never put in the filter. Ziti 1.x accepts type=1/type=2, but 2.x matches nothing with it and returns no error, so a typed filter silently deletes nothing on 2.x while every 1.x test passes. The fake reproduces this with IntegerTypeMatchesNothing; policy-selection tests loop over zitifake.Generations. unaccess.go carried a sixth such filter, not in the brief's list of five, and was converted with them.
• Client stage: the share and access commands' exit status is a contract for supervisors. 2 means the controller refused (a 4xx other than 429) and a retry cannot help; 1 means anything else, including failures that are not a controller answer (local validation, a missing Caddyfile), which are left at 1 by decision rather than classified one by one. The CLI never sleeps or retries to slow a supervisor; the agent's retry manager is the one thing that paces, and the CLI's permanent message points there. classifyFailure (cmd/zrok2/failure.go) is the one place that decides; a new generated 503 type needs adding to its retryAfterSeconds.
• A caddy backend's Run returns once caddy has started, so the share commands call it inline and treat its error as a failure to start (share deleted, then exit); the Ziti-listener backends' Run serves until Stop, so they stay in a goroutine and an error after Stop is not reported.
• disable keeps the local environment and identity on every failure, a 401 included, by operator decision on the follow-up. A revoked account token answers 401 just as an environment the controller has forgotten does, and the client cannot tell them apart, so deleting on 401 could strand a live environment. The user removes ~/.zrok2 by hand when they know the environment is gone; the message says so.

Journal 2026 10 08 (`docs/journal/2026-10-08.md`) Copy Section

2026-10-08

• The admin name lookup reads its share token from the live share-name mapping, so its answer agrees with the names list and the name availability check after a share is torn down.

Attic V0.2 Account Requests (`website/docs/_attic/v0.2_account_requests.md`) Copy Section

Account Request Process

In v0.1 Copy Chapter

The v0.1 versions of zrok had an open-access zrok create account that allows any user to create an account. Useful for closed development environments only.

In v0.2 Copy Chapter

• The zrok create account command now only takes an email address.
• The email address is submitted to an open-ended API endpoint, which then records an "account request", allocating a request token.
• An email is sent to the address offering a link with the request token, allowing the user to create the account.
• The account request is marked complete.

Invitations for Others Copy Section

This open zrok create account command will allow any user to send a zrok invitation to any user with a valid email address.

Garbage Collection Copy Section

An background garbage collector in the controller scans the account requests, looking for unused requests, which are removed after a configurable amount of time.

Attic V0.4 Limits (`website/docs/_attic/v0.4_limits.md`) Copy Section

Testing the Limits

Consider the following zrok controller configuration stanza, describing the limits we'll be using for this testing scenario:

limits:
  environments:     -1
  shares:           -1
  bandwidth:
    per_account:
      period:       5m
      warning:
        rx:         -1
        tx:         -1
        total:      -1
      limit:
        rx:         -1
        tx:         -1
        total:      -1
    per_environment:
      period:       5m
      warning:
        rx:         -1
        tx:         -1
        total:      -1
      limit:
        rx:         -1
        tx:         -1
        total:      -1
    per_share:
      period:       5m
      warning:
        rx:         -1
        tx:         -1
        total:      1048576
      limit:
        rx:         -1
        tx:         -1
        total:      2097152
  enforcing:        true
  cycle:            1m

Any limit values set to -1 are "unlimited". In this case, we're only enforcing a transfer limit on for shares. This limits configuration will send a warning when a share has transferred more than 1 megabyte in a 5 minute period, and will temporarily deactivate the share when it has transferred more than 2 megabytes in a 5 minute period.

We're going to use the zrok test loop public framework to create a number of public shares and generate traffic. Here are the parameters we'll be using:

$ zrok test loop public -l 7 -i 10000 --min-pacing-ms 100 --max-pacing-ms 1500

This configuration will create 7 shares. Each share will perform 10,000 iterations. The delay between iterations will be randomly generated with a floor of 100ms and a ceiling of 1500ms.

Let's look at the zrok controller log for this run:

First, our zrok test loop public command will create the 7 shares:

/* Detailed source-code truncated for AI context efficiency. */

Next, we observe metrics being reported from OpenZiti into the zrok metrics infrastructure for each of the 7 shares:

/* Detailed source-code truncated for AI context efficiency. */

Our first share receives a bandwidth warning, after transferring more than 1 megabyte:

[ 105.189]    INFO zrok/controller/limits.(*shareWarningAction).HandleShare: warning 'tr7vpyrzvmh0'
[ 106.192]    INFO zrok/controller/limits.sendLimitWarningEmail: limit warning email sent to '[email protected]'
[ 110.162]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: 53z6mz4re7tu, circuit: ONzzjVS0w backend {rx: 30.6 kB, tx: 30.9 kB} frontend {rx: 30.9 kB, tx: 30.6 kB}
[ 110.165]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: dh3f3jj7zhig, circuit: fNXXHVSuw backend {rx: 42.9 kB, tx: 43.3 kB} frontend {rx: 43.3 kB, tx: 42.9 kB}
[ 110.170]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: 0evcupz5k410, circuit: cNzzH4i0w backend {rx: 31.5 kB, tx: 31.7 kB} frontend {rx: 31.7 kB, tx: 31.5 kB}
[ 115.163]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: 7u9szn30ikh0, circuit: iNzXj4S0r backend {rx: 45.3 kB, tx: 45.7 kB} frontend {rx: 45.7 kB, tx: 45.3 kB}
[ 115.164]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: tr7vpyrzvmh0, circuit: MZXXjVi0w backend {rx: 36.4 kB, tx: 36.8 kB} frontend {rx: 36.8 kB, tx: 36.4 kB}
[ 115.166]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: s0uzz1p7xjrr, circuit: RZzXHVSuw backend {rx: 46.5 kB, tx: 46.9 kB} frontend {rx: 46.9 kB, tx: 46.5 kB}
[ 115.170]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: dh3f3jj7zhig, circuit: fNXXHVSuw backend {rx: 63.9 kB, tx: 64.4 kB} frontend {rx: 64.4 kB, tx: 63.9 kB}

More shares start receiving bandwidth warnings:

/* Detailed source-code truncated for AI context efficiency. */

Our first share crosses the 2 megabyte boundary and the system limits its ability to transfer additional data by removing its dial service policy:

/* Detailed source-code truncated for AI context efficiency. */

More shares become limited and are prevented from transferring data. Notice the metrics output reducing in the logs. As more shares become limited, we're naturally seeing less data transfer occurring on the OpenZiti network:

/* Detailed source-code truncated for AI context efficiency. */

By this point, we're seeing very little traffic on the OpenZiti network:

[ 290.176]    INFO zrok/controller/limits.(*shareLimitAction).HandleShare: limiting '8k6dnu7x7ag0'
[ 290.190]    INFO zrok/controller/zrokEdgeSdk.DeleteServicePolicy: deleted service policy '5UHCkXZabFHeWYHmF01Zoc' for environment 'd.wJYlpt9'
[ 290.191]    INFO zrok/controller/limits.(*shareLimitAction).HandleShare: removed dial service policy for '8k6dnu7x7ag0'
[ 295.163]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: 7u9szn30ikh0, circuit: iNzXj4S0r backend {rx: 44.0 kB, tx: 44.4 kB} frontend {rx: 44.4 kB, tx: 44.0 kB}
[ 295.178]    INFO zrok/controller/limits.(*shareLimitAction).HandleShare: limiting '7u9szn30ikh0'
[ 295.181]    INFO zrok/controller/zrokEdgeSdk.DeleteServicePolicy: deleted service policy '3dBtc3v2G70aqqDSqujQOy' for environment 'd.wJYlpt9'
[ 295.181]    INFO zrok/controller/limits.(*shareLimitAction).HandleShare: removed dial service policy for '7u9szn30ikh0'

Notice the timestamps on the log messages. There have been no metrics messages for 60 seconds.

The limits agent runs a periodic process to look for limited resources to re-enable. It produces messages like this when there are no resources to re-enable:

[ 355.183]    INFO zrok/controller/limits.(*Agent).relax: relaxing
[ 355.188]    INFO zrok/controller/limits.(*Agent).relax: share 'dh3f3jj7zhig' still over limit
[ 355.192]    INFO zrok/controller/limits.(*Agent).relax: share '0evcupz5k410' still over limit
[ 355.196]    INFO zrok/controller/limits.(*Agent).relax: share '53z6mz4re7tu' still over limit
[ 355.199]    INFO zrok/controller/limits.(*Agent).relax: share 's0uzz1p7xjrr' still over limit
[ 355.203]    INFO zrok/controller/limits.(*Agent).relax: share 'tr7vpyrzvmh0' still over limit
[ 355.207]    INFO zrok/controller/limits.(*Agent).relax: share '8k6dnu7x7ag0' still over limit
[ 355.220]    INFO zrok/controller/limits.(*Agent).relax: share '7u9szn30ikh0' still over limit
[ 415.223]    INFO zrok/controller/limits.(*Agent).relax: relaxing
[ 415.228]    INFO zrok/controller/limits.(*Agent).relax: share 'dh3f3jj7zhig' still over limit
[ 415.232]    INFO zrok/controller/limits.(*Agent).relax: share '0evcupz5k410' still over limit
[ 415.236]    INFO zrok/controller/limits.(*Agent).relax: share '53z6mz4re7tu' still over limit
[ 415.240]    INFO zrok/controller/limits.(*Agent).relax: share 's0uzz1p7xjrr' still over limit
[ 415.245]    INFO zrok/controller/limits.(*Agent).relax: share 'tr7vpyrzvmh0' still over limit
[ 415.250]    INFO zrok/controller/limits.(*Agent).relax: share '8k6dnu7x7ag0' still over limit
[ 415.253]    INFO zrok/controller/limits.(*Agent).relax: share '7u9szn30ikh0' still over limit

Enough time has finally passed that the agent is able to remove the restrictions on some of the services:

/* Detailed source-code truncated for AI context efficiency. */

And notice that we're now starting to see traffic on those shares again:

/* Detailed source-code truncated for AI context efficiency. */

Concepts Agent (`website/docs/concepts/agent.md`) Copy Section

sidebar_label: zrok agent overview sidebar_position: 3 Copy Chapter

zrok agent overview

The zrok agent centralizes management of your zrok shares and accesses as a single persistent background process. It
provides both a web-based console and a CLI. When the agent is running, zrok2 share and zrok2 access commands
delegate to it automatically.

Centralized management Copy Chapter

Without the agent running, each zrok2 share or zrok2 access command creates a separate process for each share or
access. When the agent is running:

• All shares and accesses run under a single agent process.
• The zrok2 share and zrok2 access commands delegate to the running agent automatically.
• You can stop and restart individual shares or accesses without stopping the agent.

Restart behavior Copy Chapter

The agent distinguishes between reserved and ephemeral shares when it restarts:

• Named shares started with zrok2 share public -n <namespace>:<name> or zrok2 share private --share-token <name> are automatically restarted by the agent.
• Private accesses started with zrok2 access private are automatically restarted.
• Ephemeral shares started without a name are not restarted—they exist only for the lifetime of the agent session.

Agent console Copy Chapter

The agent provides a web-based console accessible with:

zrok2 agent console

From the console, you can:

• View the status of all active shares and accesses
• Create new shares and accesses
• Stop or restart existing shares and accesses
• Monitor traffic and connection statistics

Concepts Environments (`website/docs/concepts/environments.md`) Copy Section

sidebar_label: Accounts and environments sidebar_position: 4 Copy Chapter

Accounts and environments

zrok organizes access around two foundational concepts: your account on a zrok instance, and the environment you
create on each machine you use zrok from.

Instance and account Copy Chapter

zrok is hosted software. You interact with a zrok instance, and your account on that instance is identified by a
username and password, which you use to sign in to the web console. Your account also has a secret token, which
you use to enable environments on your machines.

You create a new account with NetFoundry's zrok instance by subscribing at myzrok.io, or in a
self-hosted instance by running zrok2 invite or zrok2 admin create account.

Environment Copy Chapter

Using your secret token, you use the zrok command line to enable an environment. An environment corresponds to a
single command-line user on a specific host system.

You create a new environment with zrok2 enable, which uses your secret token once to register the environment.
After that, the environment stays authorized until you explicitly disable it with zrok2 disable. Each machine you
use zrok from needs its own environment.

Concepts Namespaces (`website/docs/concepts/namespaces.md`) Copy Section

sidebar_position: 10 Copy Chapter

Reserved names and namespaces

:::info[v2.0 feature]
This page describes the v2.0 namespace and name system. If you're migrating from v1.x, see the v2 migration
guide for details on how this replaces the old zrok reserve workflow.
:::

By default, when you create a public or private share using zrok2 share, zrok assigns it a randomly generated share
token. When you terminate the zrok2 share command, the share is deleted and the token is no longer valid. If you run
zrok2 share again, you'll receive a brand new share token.

In v2.0, zrok introduces a more powerful system for creating persistent shares through namespaces and names.

To create and manage reserved names, see Manage reserved names.

Understand namespaces and names Copy Chapter

Namespaces Copy Section

A namespace is a logical grouping for names, similar to how a DNS zone works. Think of it as a container that holds
related names. For example:

• A public namespace might correspond to share.zrok.io
• A custom namespace might correspond to your own domain like example.com

Namespaces can be:

• Open: accessible to all users of the zrok service instance
• Closed: requiring explicit grants for access

You can see available namespaces with:

zrok2 list namespaces

Names Copy Section

A name is a unique identifier within a namespace. Names can be:

• Reserved: persistent across multiple runs of zrok2 share, similar to v1.x reserved shares
• Ephemeral: temporary, deleted when the share terminates

Think of names as similar to DNS A records within a zone. For example, if you create a name api in the public
namespace (corresponding to share.zrok.io), your share is accessible at https://api.share.zrok.io.

Benefits of the namespace/name system Copy Chapter

The v2.0 namespace and name system provides several advantages over v1.x reserved shares:

• Flexibility: less coupling between environments and external names
• Portability: easily move share backends between hosts without changing public names
• Multiple names: use multiple names for the same share
• Organization: logical grouping through namespaces
• Custom domains: support for custom domain namespaces (when configured by administrators)

Concepts Personalized Frontend (`website/docs/concepts/personalized-frontend.md`) Copy Section

sidebar_position: 11 Copy Chapter

Personalized frontend

This page describes how to use a hosted, shared zrok instance (zrok.io) with your own personalized frontend to get
custom DNS and TLS for your shares.

To do this, you need a minimal VPS instance or container hosting. The size depends on your workload, but for most
modest use cases the cheapest VPS option is sufficient.

This approach gives you complete control over how your shares are exposed publicly. It works for HTTPS shares and also
for TCP and UDP ports, letting you put all of these things on the public internet while maintaining strong security for
your protected resources.

This isn't a step-by-step how-to—it's a description of the overall concept. Figure out the specific steps to implement
this style of deployment in your own environment.

Overview Copy Chapter

Imagine you have 3 different resources shared using zrok: A, B, and C. Both A and B use the proxy backend
mode to share private HTTPS resources. Share C uses the tcpTunnel backend to expose a listening port from a private
server (like a game server or a message queue).

You're using the shared zrok instance at zrok.io to provide your secure sharing infrastructure.

Your deployment looks like this:

You're creating reserved names in a namespace for the A, B, and C shares. These shares can be in a single
environment on a single host, or spread across completely different hosts anywhere in the world. You could use
significantly more than 3 shares, or fewer. The secure sharing fabric provides seamless, secure connectivity for all
of them. This implementation scales up or down as needed—use multiple hosts behind a load balancer for large workloads.

Because you're using private zrok shares, they need to be accessed using zrok2 access private. That command binds
a network listener where the share can be accessed on an address and port on the host where it runs. You can run
zrok2 access private to bind a listener for a share in as many places as you want (up to the service limit
configuration).

:::note
When you use zrok2 share public, your shared resources are accessible using the shared public frontend provided by
the service instance (zrok.io). zrok2 share private creates a private share that does not use the shared public
frontend—you need zrok2 access private to bind that share to a network address where it can be accessed.

In v2.0, you can create persistent private shares using the --share-token flag, which works similarly to reserved
names for public shares.
:::

Say you own the domain example.com and you want to expose your HTTPS shares A and B as a.example.com and
b.example.com. Your C share is a game server you want to expose as gaming.example.com:25565.

You can accomplish this with a cheap VPS (or container hosting). The VPS needs a public IP address and you need to
create DNS entries for example.com.

To do this, run 3 separate zrok2 access private commands on your VPS (see the
zrok agent how-to guides and the Linux agent service for
details on setting this up). One command each for shares A, B, and C. The command works like this:

$ zrok2 access private
Error: accepts 1 arg(s), received 0
Usage:
  zrok2 access private <shareToken> [flags]

Flags:
  -b, --bind string   The address to bind the private frontend (default "127.0.0.1:9191")
      --headless      Disable TUI and run headless
  -h, --help          help for private

Global Flags:
  -p, --panic     Panic instead of showing pretty errors
  -v, --verbose   Enable verbose logging

The --bind flag binds a network listener to a specific IP address and port on the host. Say your VPS has a public IP
of 1.2.3.4 and a loopback (127.0.0.1).

To expose your HTTPS shares, use a reverse proxy like nginx. The reverse proxy terminates TLS and reverse proxies
a.example.com and b.example.com to the network listeners for shares A and B.

Configure your VPS to persistently launch zrok2 access private for both shares. Use --bind to bind A to
127.0.0.1:9191 and B to 127.0.0.1:9192. Then configure nginx with a virtual host for a.example.com proxying
to 127.0.0.1:9191 and b.example.com proxying to 127.0.0.1:9192.

Exposing the TCP port for gaming.example.com is simply a matter of running a third zrok2 access private with
--bind 1.2.3.4:25565.

Once you've created the appropriate DNS entries and worked through TLS configuration (Let's Encrypt is your friend),
you'll have a fully functional personalized frontend for your zrok shares that you control.

Your protected resources remain disconnected from the internet and are only reachable through your personalized
endpoint.

Privacy Copy Chapter

When you use a public frontend (with zrok2 share public) at a hosted zrok instance like zrok.io, the operators of
that service have some visibility into your traffic. The load balancers in front of the public frontend maintain logs
describing all URLs accessed, plus headers and other information about the resource you're sharing.

When you create private shares using zrok2 share private and run your own zrok2 access private from another
location, the operators of the zrok service instance only know that some amount of data moved between the environment
running zrok2 share private and the zrok2 access private. No other information is available.

Concepts Private Shares (`website/docs/concepts/private-shares.mdx`) Copy Section

sidebar_position: 0 Copy Chapter

Private shares

zrok was built to share and access digital resources. A private share allows a resource to be accessed on another user's
system as if it were local to them. Only another zrok user who has your share token can access it. You're in control of
who can access your private shares by sharing the share token.

Peer-to-peer private resource sharing is one of the things that makes zrok unique.

zrok also provides public sharing of resources with non-zrok users. Public resource sharing is limited to resources
accessible over HTTP or HTTPS. Private sharing works with all resource types that zrok supports.

Peer-to-peer Copy Chapter

Private shares are accessed using the zrok2 access command, and require the accessing user to have an account on the
same service instance that they've already enabled with zrok2 enable.

The private share is identified by a share token. The accessing user uses the share token with the zrok2 access
command to create a local endpoint on their system, letting them use the shared resource as if it were local.

zrok doesn't require you to open any firewall ports or otherwise compromise the security of your local system — no
attack surface is exposed to the public internet. As soon as you terminate the zrok2 share process, you immediately
terminate any possible access to your shared resource.

The shared resource can be a development web server, a webhook from a cloud server, or low-level TCP and UDP network
connections using the tunnel backend. What matters is that access is private and can only be used by other zrok users
who have your share token.

The peer-to-peer capabilities of zrok are an important property of the underlying
OpenZiti network that zrok uses to provide connectivity between
users and resources.

To create and manage private shares, see Manage shares with the agent.

Backend modes Copy Chapter

Private shares support all backend modes. Public shares are limited to HTTP-based modes only. The modes exclusive to
private shares are:

• tcpTunnel: Forwards raw TCP traffic to a target server
• udpTunnel: Forwards raw UDP traffic to a target server
• socks: Provides a SOCKS5 proxy, tunneling TCP traffic to its destination through the share

The default mode is proxy, which forwards requests to any HTTP or HTTPS URL reachable from your machine:

zrok2 share private 80

See Backend modes for the full list.

Concepts Public Shares (`website/docs/concepts/public-shares.mdx`) Copy Section

sidebar_position: 1 Copy Chapter

Public shares

zrok supports public sharing for web-based (HTTP and HTTPS) resources. These resources are easily shared with the
general internet through public access points.

Peer-to-public Copy Chapter

Public sharing is most useful when the person or service accessing your resources doesn't have zrok running locally and
can't make use of the private sharing mode. Many users share development web servers, webhooks, and other HTTP/HTTPS
resources.

As with private sharing, public sharing doesn't require you to open any firewall ports or otherwise compromise the
security of your local environment. A public share goes away as soon as you terminate the zrok2 share command.

To create and manage public shares, see Manage shares with the agent. For
persistent public shares with a stable URL, see Reserved names and namespaces.

Backend modes Copy Chapter

Public shares support HTTP-based backend modes only:

• proxy: Forwards incoming requests to any HTTP or HTTPS URL reachable from your machine
• web: Serves a local directory as a browsable file index or static website
• drive: Exposes a local directory over WebDAV for mounting as a network drive
• caddy: Runs the built-in Caddy server using a Caddyfile you provide

The default mode is proxy, which forwards requests to any HTTP or HTTPS URL reachable from your machine:

zrok2 share public 80

See Backend modes for the full list.

Get Started Category .Json (`website/docs/get-started/_category_.json`) Copy Section

{
"label": "Get started",
"position": 2,
"link": {
"type": "doc",
"id": "get-started/index"
}
}

Get Started Create Share (`website/docs/get-started/create-share.md`) Copy Section

sidebar_label: 4. Create your first share sidebar_position: 5 Copy Chapter

Step 4: Create your first share

In this step, you'll create a public share that exposes a local HTTP service to the internet. You'll see exactly how
the share works and what its limitations are before you move on to the agent.

1. In one terminal, start zrok's built-in test endpoint:

   bash Copy

   zrok2 test endpoint

   This starts a simple HTTP listener on port 9090—just a throwaway server to give zrok something to share.

2. In another terminal, run:

   bash Copy

   zrok2 share public 9090

   zrok assigns a public URL and displays it along with the share type and a live feed of incoming requests:

3. Open that URL in a browser, or pass it to someone else—anyone with the link can reach your local service.

How shares work Copy Chapter

zrok2 share public runs in the foreground. The share is active as long as the command is running. If you open the
API console, you'll see the share appear in the visualizer with sparkline graphs showing
live activity as the share is accessed:

When a share fails to start Copy Chapter

If zrok2 share public (or share private, or access private) cannot start, it prints why and exits with a status
that says whether trying again can help. This matters when the command runs under a process supervisor such as systemd:

A supervisor should not restart the command on status 2; for example, a systemd unit can set
RestartPreventExitStatus=2. To have shares retried for you with backoff, run them through the
agent instead.

For more detail on a failure, add --verbose (-v) to print debug output. Debug output appears in headless mode
(--headless) only; the interactive display shows info-level output whether or not --verbose is given.

If the backend fails to start after the share was created (for example, a missing Caddyfile), the share is deleted
before the command exits, so the next attempt starts clean.

Stop the share Copy Chapter

Press Ctrl+C or close the terminal. The share is torn down and the URL stops working. This is by design—zrok
shares are ephemeral by default.

This is a good way to understand how zrok works, but it's not the right approach for services you need to keep
running. That's what the agent is for.

Get Started Enable Env (`website/docs/get-started/enable-env.md`) Copy Section

sidebar_label: 3. Enable your environment sidebar_position: 4 Copy Chapter

Step 3: Enable your environment

In this step, you'll enable a zrok environment on your machine using your account token. Enabling creates a secure
identity tied to your device so you can start creating shares.

Enable your environment Copy Chapter

Run this command with your account token from Step 1:

zrok2 enable <your_account_token>

After a few seconds, you'll see:

⣻  the zrok environment was successfully enabled...

Verify the environment Copy Chapter

Confirm everything is set up correctly:

zrok2 status

You should see output like this:

Config:

╭──────────────────┬────────────────────────┬────────╮
│ CONFIG           │ VALUE                  │ SOURCE │
├──────────────────┼────────────────────────┼────────┤
│ apiEndpoint      │ https://api-v2.zrok.io │ env    │
│ defaultNamespace │ public                 │ binary │
│ headless         │ false                  │ config │
│ superNetwork     │ false                  │ config │
╰──────────────────┴────────────────────────┴────────╯

Environment:

╭───────────────┬─────────╮
│ PROPERTY      │ VALUE   │
├───────────────┼─────────┤
│ Account Token │ <<SET>> │
│ EnvZId        │ <<SET>> │
╰───────────────┴─────────╯

Both Account Token and EnvZId should show <<SET>>. Your environment is ready.

:::note[Self-hosted API endpoint]
If you're using a self-hosted zrok instance, configure your API endpoint before enabling:

zrok2 config set apiEndpoint https://your-zrok-instance.example.com

Your apiEndpoint value in zrok2 status will show your instance's URL instead of https://api-v2.zrok.io.
:::

Visualize your environment Copy Chapter

If you open the API console, you'll see your new environment reflected in the
visualizer. The environment is named after your shell username and hostname. Click the environment node in the
explorer to see its details in the panel at the bottom of the page:

The visualizer supports clicking, dragging, and mouse wheel zooming. If you get lost, click the zoom-to-fit icon in
the lower-left corner of the explorer to reset the view.

:::note
With your zrok account, you can zrok2 enable multiple environments. This allows you to share (and access your
shares) from multiple environments simultaneously.
:::

Get Started Get Token (`website/docs/get-started/get-token.md`) Copy Section

sidebar_label: 1. Get an account token sidebar_position: 2 Copy Chapter

Step 1: Get an account token

In this step, you'll create a zrok account and get the account token you need to enable your environment.

myzrok.io (hosted) Copy Chapter

1. Go to myzrok.io and sign up for a free account.

2. After signing in, click the zrok icon in the left sidebar to open the API console.

3. Click the green CLICK HERE TO GET STARTED! button. The getting started wizard opens:

4. Under step 2 of the wizard, copy and save your account token (a short alphanumeric string like 7g3K6gVKikWb).
   Treat it like a password: it authenticates your device to the zrok service.

Self-hosted instance Copy Chapter

If you've deployed your own zrok instance, there are two ways to create an account:

• Self-service — If your instance has invitations enabled, run zrok2 invite and follow the prompts to register
  with your email address. See Invitations for details.

• Admin — An administrator can create an account directly:

  bash Copy

  zrok2 admin create account <username> <password>

Either way, the result is an account token. Copy it for use in Step 3: Enable your environment.

Get Started Install Zrok2 (`website/docs/get-started/install-zrok2.mdx`) Copy Section

sidebar_label: 2. Install the zrok2 command sidebar_position: 3 Copy Chapter

import InstallCards from '@zrokroot/docs/how-tos/install/_install_cards.mdx';

Step 2: Install the `zrok2` command

In this step, you'll install the zrok2 command-line tool on your device.

:::note
zrok is not supported on mobile devices.
:::

Select your operating system below. Click GUIDE for step-by-step installation instructions, or use the
architecture links to download the binary directly. If you're not sure which to pick, use the guide.

Once you've confirmed the install works with zrok2 version, continue to Step 3.

Get Started Set Up Agent (`website/docs/get-started/set-up-agent.md`) Copy Section

sidebar_label: 5. Set up the agent sidebar_position: 6 Copy Chapter

Step 5: Set up the agent

In this step, you'll set up the zrok agent—the recommended approach for always-on shares that need to survive
terminal sessions and system restarts.

Why use the agent? Copy Chapter

The foreground zrok2 share command in Step 4 stops the moment you close the terminal. The zrok agent runs in the
background, manages all your shares and accesses as a single persistent process, and provides a web UI. When the agent
is running, zrok2 share and zrok2 access commands delegate to it automatically. For a full explanation, see
zrok agent overview.

Try the agent in the foreground Copy Chapter

The foreground share from step 4 won't carry over to the agent—it started as its own process and the agent begins
fresh. You can leave it running or cancel it; either way, you'll create shares through the agent separately.

To try the agent before installing it as a service:

1. Start the agent:

   bash Copy

   zrok2 agent start

2. In another terminal, open the agent console:

   bash Copy

   zrok2 agent console

   This opens the agent UI in your browser. You can create and monitor shares from there, or continue using the
   CLI.

Install the agent as a background service Copy Chapter

For reliable, always-on shares, install the agent as a system service:

• Windows: Set up the Windows agent service
• Linux: Install the Linux agent package zrok2-agent
• Docker: Run the zrok agent in Docker

:::note
A native macOS agent package is not yet available. macOS users can run zrok2 agent start in the foreground or use a
third-party process manager.
:::

For more detail on managing shares with the agent, see Manage shares with the agent.

How Tos Category .Json (`website/docs/how-tos/_category_.json`) Copy Section

{
"label": "How-to guides",
"position": 3,
"link": {
"type": "generated-index",
"description": "Step-by-step guides for installing zrok, sharing resources, and using advanced features."
}
}

How Tos Linux Agent Install (`website/docs/how-tos/_linux-agent-install.mdx`) Copy Section

1. Set up zrok's Linux package repository by following the Linux install guide, or run this one-liner to complete the repo setup and install packages.

   bash Copy

   curl -sSLf https://get.openziti.io/install.bash \
   | sudo bash -s zrok2-agent

2. If you previously set up the repository by following the guide, then also install the zrok2-agent package. This package provides the systemd service.

   bash title="ubuntu, debian" Copy

   sudo apt install zrok2-agent

   bash title="fedora, rocky" Copy

   sudo dnf install zrok2-agent

Myzrok Category .Json (`website/docs/myzrok/_category_.json`) Copy Section

{
"label": "myzrok",
"position": 6,
"link": {
"type": "generated-index",
"description": "Account management, service limits, and custom domains for the hosted myzrok.io service."
}
}

Myzrok Custom Domains (`website/docs/myzrok/custom-domains.md`) Copy Section

title: Add a custom domain sidebar_position: 120 Copy Chapter

myzrok.io lets you use your own DNS name for zrok shares. For example, if you own foo.example.io,
you can create ephemeral shares like https://vw8jbg4ijz5g.foo.example.io or
reserved shares like https://toaster.foo.example.io.

Prerequisites Copy Chapter

• You must own the domain you want to use and have access to its DNS settings.
• Custom domains require a Pro subscription with myzrok.io.

Add your domain Copy Chapter

1. Sign in to the myzrok console and click the globe icon in the left navigation to open the Custom Domains page:

2. Click Create in the top right corner.

3. Enter your domain name and click Create. zrok begins issuing a managed TLS certificate for your domain:

4. Close the form. Return when your domain status changes to pending validation—this usually takes a few minutes.

Create DNS records Copy Chapter

zrok needs two DNS records: a CNAME to validate domain ownership for certificate issuance, and an A record to route traffic.

1. Create a CNAME record with the name and value shown in the form:

2. Create an A record pointing your domain to the static IPs provided:

3. Verify your records resolve correctly using the nslookup command shown in the form:

   text Copy

   nslookup test.foo.example.io
   Server:        192.168.86.194
   Address:    192.168.86.194#53
   
   Non-authoritative answer:
   Name:    test.foo.example.io
   Address: 99.83.220.186
   Name:    test.foo.example.io
   Address: 52.223.6.108

   If the command returns the A-record IPs, DNS is resolving correctly.

4. Close the form. zrok validates your records and issues the certificate within a few minutes.

Finalize your domain Copy Chapter

Within 72 hours of certificate issuance, click Finalize to complete setup:

myzrok.io will finish the final steps automatically—this takes about a minute.

Start sharing Copy Chapter

To create shares that use your custom domain, specify the --frontend flag:

zrok2 share public --frontend foo-example--goPIhgtJtz

To set it as the default for your environment:

zrok2 config set defaultNamespace foo-example--goPIhgtJtz

To confirm the active frontend, run zrok2 status:

Myzrok Service Limits (`website/docs/myzrok/service-limits.md`) Copy Section

title: Service limits Copy Chapter

NetFoundry's public zrok instance implements limits based on pricing tier, as well as rate limits to protect the service for all users.

Limits on shares, environments, or bandwidth Copy Chapter

The number of shares, environments, or allowed bandwidth is based on your myzrok subscription.
These limits are defined on the zrok pricing page.
Bandwidth limits are based on a rolling 24-hour window.

:::warning
If you exceed the daily bandwidth of your plan, any running shares are disabled and the zrok API prevents new shares
from being created until bandwidth falls below the 24-hour limit.
:::

Rate limits for public shares Copy Chapter

Public shares are subject to API rate limiting by IP address and by individual share token, to protect the zrok service
so that one user doesn't negatively impact others.

The rate limiter allows bursts up to the limit within a shorter timespan. Once exceeded, new requests are blocked until
the rate falls below the 300-second window threshold.

Myzrok Upgrading (`website/docs/myzrok/upgrading.md`) Copy Section

title: Upgrade from 0.4 to 1.0 Copy Chapter

This guide is for users migrating from 0.4 to an older 1.x release.

:::note

• For the latest zrok version, see Install zrok.
• As of zrok 1.0.2, the rebase is automatic and the configuration updates to the v1 API with no action required.
  :::

Rebase your environment Copy Chapter

If you're running version 1.0.0 or 1.0.1, rebase your environment to use the new versioned API:

zrok rebase apiEndpoint https://api-v1.zrok.io

You can now resume normal zrok API interactions.

Troubleshoot after upgrade Copy Chapter

If you run into issues, first verify your zrok version:

zrok version

Then review your configuration. If you're running version 1.0 or later, apiEndpoint should be https://api-v1.zrok.io:

zrok status

If you're still having issues, visit the zrok discourse forum.

Reset your environment Copy Section

If you prefer to reset your environment from scratch:

:::warning
Running zrok disable deletes any running environments and shares, and releases any reserved shares.
:::

1. Disable your current environment:

   shell Copy

   zrok disable

2. Reset the API endpoint to the default:

   shell Copy

   zrok config unset apiEndpoint

3. Create a fresh environment:

   shell Copy

   zrok enable <your account token>

Self Hosting Category .Json (`website/docs/self-hosting/_category_.json`) Copy Section

{
"label": "Self-hosting",
"position": 5,
"link": {
"type": "generated-index",
"description": "Deploy and operate your own zrok instance on Linux, Docker, or Kubernetes. These guides cover configuration, OAuth authentication, metrics and limits, organizations, and user management."
}
}

Self Hosting Instance Configuration (`website/docs/self-hosting/instance-configuration.mdx`) Copy Section

sidebar_position: 90 Copy Chapter

Use another zrok instance

:::note
This guide is relevant if you're self-hosting or using a friend's zrok instance instead of using zrok-as-a-service from
zrok.io.
:::

The zrok command on your computer uses a zrok instance over the network.

The default API endpoint for the zrok command is api-v2.zrok.io. To point to a different instance:

zrok2 config set apiEndpoint https://zrok.example.com

[WARNING]: unable to open environment metadata; ignoring

zrok configuration updated

:::note
The WARNING about environment metadata is expected when you run zrok2 config set before zrok2 enable.
:::

Use zrok2 status to inspect the state of your local environment. In zrok, an environment is each shell where
you install and enable a copy of zrok.

zrok2 status

Config:

 CONFIG       VALUE                      SOURCE
 apiEndpoint  https://zrok.mydomain.com  config

[WARNING]: Unable to load your local environment!

To create a local environment use the zrok2 enable command.

The zrok2 status command shows the API endpoint your environment is using and the SOURCE where the value was
retrieved. Here, config means the value was set with the zrok2 config command.

Sdk Python Src Docs Access201Response (`sdk/python/src/docs/Access201Response.md`) Copy Section

Access201Response

Properties Copy Chapter

Example Copy Chapter

from zrok_api.models.access201_response import Access201Response

# TODO update the JSON string below
json = "{}"
# create an instance of Access201Response from a JSON string
access201_response_instance = Access201Response.from_json(json)
# print the JSON string representation of the object
print(Access201Response.to_json())

# convert the object into a dict
access201_response_dict = access201_response_instance.to_dict()
# create an instance of Access201Response from a dict
access201_response_from_dict = Access201Response.from_dict(access201_response_dict)

[Back to Model list] [Back to API list] [Back to README]

Sdk Python Src Docs AccessRequest (`sdk/python/src/docs/AccessRequest.md`) Copy Section

AccessRequest

Properties Copy Chapter

Example Copy Chapter

from zrok_api.models.access_request import AccessRequest

# TODO update the JSON string below
json = "{}"
# create an instance of AccessRequest from a JSON string
access_request_instance = AccessRequest.from_json(json)
# print the JSON string representation of the object
print(AccessRequest.to_json())

# convert the object into a dict
access_request_dict = access_request_instance.to_dict()
# create an instance of AccessRequest from a dict
access_request_from_dict = AccessRequest.from_dict(access_request_dict)

[Back to Model list] [Back to API list] [Back to README]

Sdk Python Src Docs AccessSummary (`sdk/python/src/docs/AccessSummary.md`) Copy Section

AccessSummary

Properties Copy Chapter

Example Copy Chapter

from zrok_api.models.access_summary import AccessSummary

# TODO update the JSON string below
json = "{}"
# create an instance of AccessSummary from a JSON string
access_summary_instance = AccessSummary.from_json(json)
# print the JSON string representation of the object
print(AccessSummary.to_json())

# convert the object into a dict
access_summary_dict = access_summary_instance.to_dict()
# create an instance of AccessSummary from a dict
access_summary_from_dict = AccessSummary.from_dict(access_summary_dict)

[Back to Model list] [Back to API list] [Back to README]

Sdk Python Src Docs AccessesList (`sdk/python/src/docs/AccessesList.md`) Copy Section

AccessesList

Properties Copy Chapter

Example Copy Chapter

from zrok_api.models.accesses_list import AccessesList

# TODO update the JSON string below
json = "{}"
# create an instance of AccessesList from a JSON string
accesses_list_instance = AccessesList.from_json(json)
# print the JSON string representation of the object
print(AccessesList.to_json())

# convert the object into a dict
accesses_list_dict = accesses_list_instance.to_dict()
# create an instance of AccessesList from a dict
accesses_list_from_dict = AccessesList.from_dict(accesses_list_dict)

[Back to Model list] [Back to API list] [Back to README]

Sdk Python Src Docs AccountApi (`sdk/python/src/docs/AccountApi.md`) Copy Section

zrok_api.AccountApi

All URIs are relative to /api/v2

**change_password**

change_password(body=body)

Example Copy Section

• Api Key Authentication (key):

import zrok_api
from zrok_api.models.change_password_request import ChangePasswordRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: key
configuration.api_key['key'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['key'] = 'Bearer'

# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AccountApi(api_client)
    body = zrok_api.ChangePasswordRequest() # ChangePasswordRequest |  (optional)

    try:
        api_instance.change_password(body=body)
    except Exception as e:
        print("Exception when calling AccountApi->change_password: %s\n" % e)

Parameters Copy Section

Return type Copy Section

void (empty response body)

Authorization Copy Section

key

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: application/zrok.v1+json

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**invite**

invite(body=body)

Example Copy Section

import zrok_api
from zrok_api.models.invite_request import InviteRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)


# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AccountApi(api_client)
    body = zrok_api.InviteRequest() # InviteRequest |  (optional)

    try:
        api_instance.invite(body=body)
    except Exception as e:
        print("Exception when calling AccountApi->invite: %s\n" % e)

Parameters Copy Section

Return type Copy Section

void (empty response body)

Authorization Copy Section

No authorization required

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: application/zrok.v1+json

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**login**

str login(body=body)

Example Copy Section

import zrok_api
from zrok_api.models.login_request import LoginRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)


# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AccountApi(api_client)
    body = zrok_api.LoginRequest() # LoginRequest |  (optional)

    try:
        api_response = api_instance.login(body=body)
        print("The response of AccountApi->login:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling AccountApi->login: %s\n" % e)

Parameters Copy Section

Return type Copy Section

str

Authorization Copy Section

No authorization required

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: application/zrok.v1+json

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**regenerate_account_token**

RegenerateAccountToken200Response regenerate_account_token(body=body)

Example Copy Section

• Api Key Authentication (key):

/* Detailed source-code truncated for AI context efficiency. */

Parameters Copy Section

Return type Copy Section

RegenerateAccountToken200Response

Authorization Copy Section

key

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: application/zrok.v1+json

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**register**

RegenerateAccountToken200Response register(body=body)

Example Copy Section

import zrok_api
from zrok_api.models.regenerate_account_token200_response import RegenerateAccountToken200Response
from zrok_api.models.register_request import RegisterRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)


# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AccountApi(api_client)
    body = zrok_api.RegisterRequest() # RegisterRequest |  (optional)

    try:
        api_response = api_instance.register(body=body)
        print("The response of AccountApi->register:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling AccountApi->register: %s\n" % e)

Parameters Copy Section

Return type Copy Section

RegenerateAccountToken200Response

Authorization Copy Section

No authorization required

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: application/zrok.v1+json

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**reset_password**

reset_password(body=body)

Example Copy Section

import zrok_api
from zrok_api.models.reset_password_request import ResetPasswordRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)


# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AccountApi(api_client)
    body = zrok_api.ResetPasswordRequest() # ResetPasswordRequest |  (optional)

    try:
        api_instance.reset_password(body=body)
    except Exception as e:
        print("Exception when calling AccountApi->reset_password: %s\n" % e)

Parameters Copy Section

Return type Copy Section

void (empty response body)

Authorization Copy Section

No authorization required

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: application/zrok.v1+json

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**reset_password_request**

reset_password_request(body=body)

Example Copy Section

import zrok_api
from zrok_api.models.regenerate_account_token_request import RegenerateAccountTokenRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)


# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AccountApi(api_client)
    body = zrok_api.RegenerateAccountTokenRequest() # RegenerateAccountTokenRequest |  (optional)

    try:
        api_instance.reset_password_request(body=body)
    except Exception as e:
        print("Exception when calling AccountApi->reset_password_request: %s\n" % e)

Parameters Copy Section

Return type Copy Section

void (empty response body)

Authorization Copy Section

No authorization required

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: Not defined

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**verify**

Verify200Response verify(body=body)

Example Copy Section

import zrok_api
from zrok_api.models.verify200_response import Verify200Response
from zrok_api.models.verify_request import VerifyRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)


# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AccountApi(api_client)
    body = zrok_api.VerifyRequest() # VerifyRequest |  (optional)

    try:
        api_response = api_instance.verify(body=body)
        print("The response of AccountApi->verify:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling AccountApi->verify: %s\n" % e)

Parameters Copy Section

Return type Copy Section

Verify200Response

Authorization Copy Section

No authorization required

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: application/zrok.v1+json

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

Sdk Python Src Docs AddFrontendGrantRequest (`sdk/python/src/docs/AddFrontendGrantRequest.md`) Copy Section

AddFrontendGrantRequest

Properties Copy Chapter

Example Copy Chapter

from zrok_api.models.add_frontend_grant_request import AddFrontendGrantRequest

# TODO update the JSON string below
json = "{}"
# create an instance of AddFrontendGrantRequest from a JSON string
add_frontend_grant_request_instance = AddFrontendGrantRequest.from_json(json)
# print the JSON string representation of the object
print(AddFrontendGrantRequest.to_json())

# convert the object into a dict
add_frontend_grant_request_dict = add_frontend_grant_request_instance.to_dict()
# create an instance of AddFrontendGrantRequest from a dict
add_frontend_grant_request_from_dict = AddFrontendGrantRequest.from_dict(add_frontend_grant_request_dict)

[Back to Model list] [Back to API list] [Back to README]

Sdk Python Src Docs AddNamespaceFrontendMappingRequest (`sdk/python/src/docs/AddNamespaceFrontendMappingRequest.md`) Copy Section

AddNamespaceFrontendMappingRequest

Properties Copy Chapter

Example Copy Chapter

from zrok_api.models.add_namespace_frontend_mapping_request import AddNamespaceFrontendMappingRequest

# TODO update the JSON string below
json = "{}"
# create an instance of AddNamespaceFrontendMappingRequest from a JSON string
add_namespace_frontend_mapping_request_instance = AddNamespaceFrontendMappingRequest.from_json(json)
# print the JSON string representation of the object
print(AddNamespaceFrontendMappingRequest.to_json())

# convert the object into a dict
add_namespace_frontend_mapping_request_dict = add_namespace_frontend_mapping_request_instance.to_dict()
# create an instance of AddNamespaceFrontendMappingRequest from a dict
add_namespace_frontend_mapping_request_from_dict = AddNamespaceFrontendMappingRequest.from_dict(add_namespace_frontend_mapping_request_dict)

[Back to Model list] [Back to API list] [Back to README]

Sdk Python Src Docs AddNamespaceGrantRequest (`sdk/python/src/docs/AddNamespaceGrantRequest.md`) Copy Section

AddNamespaceGrantRequest

Properties Copy Chapter

Example Copy Chapter

from zrok_api.models.add_namespace_grant_request import AddNamespaceGrantRequest

# TODO update the JSON string below
json = "{}"
# create an instance of AddNamespaceGrantRequest from a JSON string
add_namespace_grant_request_instance = AddNamespaceGrantRequest.from_json(json)
# print the JSON string representation of the object
print(AddNamespaceGrantRequest.to_json())

# convert the object into a dict
add_namespace_grant_request_dict = add_namespace_grant_request_instance.to_dict()
# create an instance of AddNamespaceGrantRequest from a dict
add_namespace_grant_request_from_dict = AddNamespaceGrantRequest.from_dict(add_namespace_grant_request_dict)

[Back to Model list] [Back to API list] [Back to README]

Sdk Python Src Docs AddOrganizationMemberRequest (`sdk/python/src/docs/AddOrganizationMemberRequest.md`) Copy Section

AddOrganizationMemberRequest

Properties Copy Chapter

Example Copy Chapter

from zrok_api.models.add_organization_member_request import AddOrganizationMemberRequest

# TODO update the JSON string below
json = "{}"
# create an instance of AddOrganizationMemberRequest from a JSON string
add_organization_member_request_instance = AddOrganizationMemberRequest.from_json(json)
# print the JSON string representation of the object
print(AddOrganizationMemberRequest.to_json())

# convert the object into a dict
add_organization_member_request_dict = add_organization_member_request_instance.to_dict()
# create an instance of AddOrganizationMemberRequest from a dict
add_organization_member_request_from_dict = AddOrganizationMemberRequest.from_dict(add_organization_member_request_dict)

[Back to Model list] [Back to API list] [Back to README]

Sdk Python Src Docs AdminApi (`sdk/python/src/docs/AdminApi.md`) Copy Section

zrok_api.AdminApi

All URIs are relative to /api/v2

**add_frontend_grant**

add_frontend_grant(body=body)

Example Copy Section

• Api Key Authentication (key):

import zrok_api
from zrok_api.models.add_frontend_grant_request import AddFrontendGrantRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: key
configuration.api_key['key'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['key'] = 'Bearer'

# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AdminApi(api_client)
    body = zrok_api.AddFrontendGrantRequest() # AddFrontendGrantRequest |  (optional)

    try:
        api_instance.add_frontend_grant(body=body)
    except Exception as e:
        print("Exception when calling AdminApi->add_frontend_grant: %s\n" % e)

Parameters Copy Section

Return type Copy Section

void (empty response body)

Authorization Copy Section

key

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: application/zrok.v1+json

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**add_namespace_frontend_mapping**

add_namespace_frontend_mapping(body=body)

Example Copy Section

• Api Key Authentication (key):

import zrok_api
from zrok_api.models.add_namespace_frontend_mapping_request import AddNamespaceFrontendMappingRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: key
configuration.api_key['key'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['key'] = 'Bearer'

# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AdminApi(api_client)
    body = zrok_api.AddNamespaceFrontendMappingRequest() # AddNamespaceFrontendMappingRequest |  (optional)

    try:
        api_instance.add_namespace_frontend_mapping(body=body)
    except Exception as e:
        print("Exception when calling AdminApi->add_namespace_frontend_mapping: %s\n" % e)

Parameters Copy Section

Return type Copy Section

void (empty response body)

Authorization Copy Section

key

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: Not defined

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**add_namespace_grant**

add_namespace_grant(body=body)

Example Copy Section

• Api Key Authentication (key):

import zrok_api
from zrok_api.models.add_namespace_grant_request import AddNamespaceGrantRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: key
configuration.api_key['key'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['key'] = 'Bearer'

# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AdminApi(api_client)
    body = zrok_api.AddNamespaceGrantRequest() # AddNamespaceGrantRequest |  (optional)

    try:
        api_instance.add_namespace_grant(body=body)
    except Exception as e:
        print("Exception when calling AdminApi->add_namespace_grant: %s\n" % e)

Parameters Copy Section

Return type Copy Section

void (empty response body)

Authorization Copy Section

key

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: Not defined

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**add_organization_member**

add_organization_member(body=body)

Example Copy Section

• Api Key Authentication (key):

import zrok_api
from zrok_api.models.add_organization_member_request import AddOrganizationMemberRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: key
configuration.api_key['key'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['key'] = 'Bearer'

# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AdminApi(api_client)
    body = zrok_api.AddOrganizationMemberRequest() # AddOrganizationMemberRequest |  (optional)

    try:
        api_instance.add_organization_member(body=body)
    except Exception as e:
        print("Exception when calling AdminApi->add_organization_member: %s\n" % e)

Parameters Copy Section

Return type Copy Section

void (empty response body)

Authorization Copy Section

key

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: Not defined

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**apply_limit_classes**

apply_limit_classes(body=body)

Example Copy Section

• Api Key Authentication (key):

import zrok_api
from zrok_api.models.apply_limit_classes_request import ApplyLimitClassesRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: key
configuration.api_key['key'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['key'] = 'Bearer'

# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AdminApi(api_client)
    body = zrok_api.ApplyLimitClassesRequest() # ApplyLimitClassesRequest |  (optional)

    try:
        api_instance.apply_limit_classes(body=body)
    except Exception as e:
        print("Exception when calling AdminApi->apply_limit_classes: %s\n" % e)

Parameters Copy Section

Return type Copy Section

void (empty response body)

Authorization Copy Section

key

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: Not defined

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**create_account**

RegenerateAccountToken200Response create_account(body=body)

Example Copy Section

• Api Key Authentication (key):

import zrok_api
from zrok_api.models.login_request import LoginRequest
from zrok_api.models.regenerate_account_token200_response import RegenerateAccountToken200Response
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: key
configuration.api_key['key'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['key'] = 'Bearer'

# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AdminApi(api_client)
    body = zrok_api.LoginRequest() # LoginRequest |  (optional)

    try:
        api_response = api_instance.create_account(body=body)
        print("The response of AdminApi->create_account:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling AdminApi->create_account: %s\n" % e)

Parameters Copy Section

Return type Copy Section

RegenerateAccountToken200Response

Authorization Copy Section

key

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: application/zrok.v1+json

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**create_frontend**

CreateFrontend201Response create_frontend(body=body)

Example Copy Section

• Api Key Authentication (key):

import zrok_api
from zrok_api.models.create_frontend201_response import CreateFrontend201Response
from zrok_api.models.create_frontend_request import CreateFrontendRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: key
configuration.api_key['key'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['key'] = 'Bearer'

# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AdminApi(api_client)
    body = zrok_api.CreateFrontendRequest() # CreateFrontendRequest |  (optional)

    try:
        api_response = api_instance.create_frontend(body=body)
        print("The response of AdminApi->create_frontend:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling AdminApi->create_frontend: %s\n" % e)

Parameters Copy Section

Return type Copy Section

CreateFrontend201Response

Authorization Copy Section

key

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: application/zrok.v1+json

HTTP response details Copy Section

[Back to top] [Back to API list] [Back to Model list] [Back to README]

**create_identity**

CreateIdentity201Response create_identity(body=body)

Example Copy Section

• Api Key Authentication (key):

import zrok_api
from zrok_api.models.create_identity201_response import CreateIdentity201Response
from zrok_api.models.create_identity_request import CreateIdentityRequest
from zrok_api.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to /api/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = zrok_api.Configuration(
    host = "/api/v2"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: key
configuration.api_key['key'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['key'] = 'Bearer'

# Enter a context with an instance of the API client
with zrok_api.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = zrok_api.AdminApi(api_client)
    body = zrok_api.CreateIdentityRequest() # CreateIdentityRequest |  (optional)

    try:
        api_response = api_instance.create_identity(body=body)
        print("The response of AdminApi->create_identity:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling AdminApi->create_identity: %s\n" % e)

Parameters Copy Section

Return type Copy Section

CreateIdentity201Response

Authorization Copy Section

key

HTTP request headers Copy Section

• Content-Type: application/zrok.v1+json
• Accept: application/zrok.v1+json

HTTP response details Copy Section