Troubleshooting

If something isn't working as expected, walk through the relevant section below before reaching out. Most issues come down to one of: auth, validation limits, attached resources not re-attached after restore, or the guest application itself.

Session creation hangs or never becomes ready

Check, in order:

1. Endpoint: is TENKI_API_URL (or WithBaseURL) pointing at the right environment?
2. Auth token: is TENKI_API_KEY set, valid, and not expired?
3. Resource limits: is --cpu between 1 and 16 and --memory-mb between 512 and 65536?
4. Snapshot: if you passed --snapshot, does it have a READY state?

Inspect the session record directly:

tenki sandbox get --session <session-id> --json

Snapshot restore works but data from a prior volume is missing

That is expected unless you re-attach the volume. Snapshots do not automatically restore prior volume attachments.

Re-attach explicitly:

tenki sandbox create --snapshot <snapshot-id> --volume <volume-id>:/workspace/cache

Or after the session is up:

tenki sandbox volume attach <session-id> <volume-id> --mount /workspace/cache

SSH fails

Check:

• the session still exists and is READY (tenki sandbox get --session <session-id>)
• your keys were added at create time (--authorized-key / --authorized-keys-file) or via ssh-keys set
• if you're using the managed SSH config, run tenki sandbox ssh config status to verify the assets are installed
• the session was created with inbound enabled if your environment requires it

Reset the authorized keys to a known-good set:

tenki sandbox ssh-keys set --session <session-id> --keys-file ~/.ssh/authorized_keys

Port exposure fails

Check:

1. The app is actually listening inside the guest. Verify with tenki sandbox exec ... -c 'ss -tlnp'.
2. The right port is exposed. tenki sandbox ports --session <session-id> lists the active set.
3. Inbound is allowed. The session must have been created with --allow-inbound. You cannot toggle inbound after create.

Don't hard-code preview hostnames in client code. Always use the preview_url returned by expose.

Command execution times out

Increase the timeout:

tenki sandbox exec --session <session-id> --timeout 5m -c 'long-running-command'

result, err := session.Exec(
  ctx,
  "bash",
  tenkisandbox.WithArgs("-lc", "long-running-command"),
  tenkisandbox.WithTimeout(5*time.Minute),
)

If you need to keep running an unbounded process, run it in the background inside the guest (nohup ... & or a systemd unit if your base image provides one) and poll for completion with subsequent exec calls.

exec reports flag provided but not defined: -lc

exec parses its own flags first, so -lc is read as a CLI flag rather than a shell argument. To run a shell one-liner, use -c (tenki sandbox exec -c '...'). To pass flags straight to a specific program, put them after -- so the CLI stops parsing its own flags (tenki sandbox exec -- bash -lc '...').

exec hangs when starting a background server

exec streams the command's stdout and stderr until they close. A process backgrounded with a bare & still holds those streams open, so exec waits for it forever (for example python3 -m http.server 3000 & never returns).

Redirect the background process's output and detach its stdin so it no longer holds the stream:

tenki sandbox exec -c 'python3 -m http.server 3000 >/tmp/server.log 2>&1 </dev/null &'

exec returns as soon as the foreground shell exits, and the server keeps running. Then tenki sandbox expose --port 3000.

Auth errors

Volume errors

CLI rejects bare numeric sizes:

# rejected
tenki sandbox volume create ... --size 1024

# accepted
tenki sandbox volume create ... --size 10GB
tenki sandbox volume create ... --size 10GiB

Still stuck?

Email us at hello@tenki.cloud with:

• the session or snapshot ID
• the CLI command or SDK call you ran
• the full error message
• the time of the failure