Sandbox

Quickstart

Spin up your first Tenki Sandbox session in under a minute. Install the CLI or SDK, authenticate with an API key, and run commands inside an isolated Linux microVM.

Tenki Sandbox gives you disposable Linux microVMs you can drive from the CLI or the Go, TypeScript, and Python SDKs. This guide takes you from install to a running sandbox in a few minutes. Pick your tool in the first code block and the selection follows you down the page.

1. Install

curl -fsSL https://tenki.cloud/install.sh | bash

Pin a version with bash -s -- --version <x> or change the location with TENKI_INSTALL_DIR. See the CLI Reference for more.

npm install @tenkicloud/sandbox
go get github.com/TenkiCloud/tenki-sdk-go/sandbox

Requires Python 3.10+.

pip install tenki-sandbox

2. Authenticate

Sign the CLI in interactively. For SDKs and automation, Sandbox onboarding creates an initial API key that you export as TENKI_API_KEY. See Manage API keys to create additional keys, choose an expiration date, rotate keys, or revoke them.

# Opens your browser to sign in, then auto-selects a workspace and project
tenki login

# Confirm you are signed in
tenki status

Prefer a key? Run tenki login --api-key tk_your_api_key. See Authentication for headless and CI options.

export TENKI_API_KEY=tk_your_api_key
export TENKI_API_KEY=tk_your_api_key
export TENKI_API_KEY=tk_your_api_key

3. Create a sandbox and run a command

Create a session, run a command inside it, and read the output back. The session is a fresh microVM, isolated from your machine.

# Create a session (waits for RUNNING and prints the session ID)
tenki sandbox create --name demo

# Make it your current session so later commands can omit --session
tenki sandbox set <session-id>

# Run a command inside it
tenki sandbox exec -c 'uname -a && whoami'

# Tear it down
tenki sandbox terminate
// sandbox.ts
import { stdoutText, TenkiSandbox } from "@tenkicloud/sandbox";

const sandbox = new TenkiSandbox(); // reads TENKI_API_KEY from env

await using session = await sandbox.createAndWait({ name: "demo" });

const result = await session.exec("bash", { args: ["-lc", "uname -a && whoami"] });
console.log(`exit=${result.exitCode}\n${stdoutText(result)}`);
// `await using` closes the session when it leaves scope.

Run it:

npx tsx sandbox.ts
// main.go
package main

import (
  "context"
  "log"
  "time"

  tenkisandbox "github.com/TenkiCloud/tenki-sdk-go/sandbox"
)

func main() {
  ctx := context.Background()

  client, err := tenkisandbox.New() // reads TENKI_API_KEY from env
  if err != nil {
    log.Fatal(err)
  }
  defer client.Close()

  session, err := client.CreateAndWait(ctx, 3*time.Minute, tenkisandbox.WithName("demo"))
  if err != nil {
    log.Fatal(err)
  }
  defer session.Close(ctx) // tears the session down on return

  result, err := session.Exec(ctx, "bash", tenkisandbox.WithArgs("-lc", "uname -a && whoami"))
  if err != nil {
    log.Fatal(err)
  }
  log.Printf("exit=%d\n%s", result.ExitCode, result.StdoutString())
}

Run it:

go run main.go
# sandbox.py
from tenki_sandbox import Sandbox

# Reads TENKI_API_KEY from env. Waits for RUNNING; closes on block exit.
with Sandbox.create(name="demo") as sb:
    result = sb.exec("bash", "-lc", "uname -a && whoami")
    print(f"exit={result.exit_code}\n{result.stdout_text}")

Run it:

python sandbox.py

You should see the guest's kernel info and username printed back. That output came from inside the microVM.

What's next

Need help? Email hello@tenki.cloud and we'll help you get set up.