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 or template: if you passed --snapshot or --template, does it have a READY state / READY build?

Inspect the session record directly:

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

Template build fails

A failed build leaves a record you can inspect:

tenki sandbox template get <template-id>

Look for:

• build.error
• build.log_tail (last 128 KiB)
• build.log_truncated (true if the tail was clipped)
• build.log_artifact_id (full gzipped log artifact, if storage is configured)

In the SDK:

build, err := client.GetTemplateBuild(ctx, buildID)
fmt.Println(build.Error, build.LogTail)

If you need the full artifact, use the GetArtifactDownloadUrl RPC. See SDK reference / Advanced API surface.

Snapshot restore works but data from a prior volume is missing

That is expected unless you re-attach the volume. Snapshots and templates 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 ... bash -lc '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 bash -lc '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 template provides one) and poll for completion with subsequent exec calls.

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 [email protected] with:

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