Config lives at ~/.config/seikan/config.json (override with SEIKAN_CONFIG), storing the server, the client key, the declared tunnels, and a per-tunnel connect-token cache. The one exception is up, the container entrypoint, which takes everything from the environment and reads and writes nothing.

Getting a client key onto a machine has two shapes. seikan init --server <host> asks the server to let this machine in, prints a confirmation code, and waits for an administrator to approve it — nothing secret travels between machines, and Ctrl-C is safe: re-running resumes the same request. seikan init --server <host> --api-key sk_… uses a key an administrator issued and gave you directly.

There are two ways to run a tunnel. add + start is the persistent one: tunnels are declared in the config and served by a background OS service that survives logout and restarts on failure. serve is the ad-hoc one: a single tunnel in the foreground, gone when you Ctrl-C.

In a container it is neither: up serves one tunnel described entirely by environment variables, with no config file to write and no setup step to run first. See below.

Managing tunnels

Managing the background service

Linux uses a per-user systemctl --user unit, macOS a launchd LaunchAgent. Both run as your own user — no root.

Everything else

Common flags

Note: Reconnect — serve/connect reconnect automatically with backoff if the tunnel drops (e.g. after a server update) and recover within ~1s. A rejected token exits immediately. Ctrl-C stops cleanly.

Running in a container

up exists because the rest of the CLI assumes a machine someone logs into: init writes a config file and everything else reads it back. A container has no such file — and the published image is distroless with no writable home — so up takes the whole tunnel from the environment and does the admin-API work itself on start.

Exactly one of SEIKAN_DOMAIN / SEIKAN_TCP_PORT (with a client key); every value also has a flag, so up is usable outside a container.

On start it finds the frontend its environment describes and rotates its connect token, or creates the frontend if there isn't one. Rotating rather than recreating is what makes a restart cheap: the frontend keeps its ID and its route, so the public side never stops resolving. A token is only ever shown once, at creation, so a container with no state has no other way back in — and the previous token stops working the moment it rotates, which is why exactly one container should run any given frontend.

It exits non-zero, without retrying, on anything retrying cannot fix: a rejected key, a domain or port owned by another client key, a filled quota. An admin API that simply isn't up yet is retried with backoff, since in a compose file the client and server start in the same second.

Private peer tunnels

A peer frontend relays a connection between two clients through the server — nothing is ever exposed publicly, not even briefly. Useful for reaching a database or internal service on one box from another, without opening a public port for it.

It has two independent one-time secrets, minted together and never interchangeable:

• Provider token — registers the backend (the box with the actual service). Works exactly like a TCP frontend's token: serve --peer caches it locally and reconnects automatically.
• Consumer token — relays a connection into the frontend. It is never cached locally; it's printed once, at creation time, for you to hand to whatever needs to reach the tunnel. Holding only the consumer token never lets you register a fake backend, so sharing it is safe even for something like a database credential.

# Box A — has the service (e.g. Postgres on :5432):
seikan serve --peer --name pgdb 5432

Created peer frontend "pgdb". Share this with whatever should reach it (never shown again):
  seikan forward --server tunnel.example.com:443 --token sk_t_... --listen 5432

# Box B — wants to reach it:
seikan forward --server tunnel.example.com:443 --token sk_t_... --listen 5432
psql -h localhost -p 5432

Box B needs no client config or client key — just the printed command. A peer frontend never binds a public port and needs no domain or TLS certificate; list/rm on box A manage it like any other frontend.