Together Sandbox

Tools for working with Together AI sandboxes: a CLI, a TypeScript SDK, and a Python SDK.

Install

# CLI
curl -fsSL https://raw.githubusercontent.com/togethercomputer/together-sandbox/main/install.sh | bash

# TypeScript SDK
npm install together-sandbox

# Python SDK
pip install together-sandbox

The CLI installs to ~/.local/bin and never needs sudo; if that directory isn't on your PATH, the installer prints the line to add. See the CLI docs for INSTALL_DIR and version pinning.

Get an API key

All three packages authenticate via the TOGETHER_API_KEY environment variable.

1. Sign in (or sign up) at together.ai.

2. Open your project's API keys page.

3. Click Create key, give it a name, and copy the value.

4. Export it in your shell (or add it to your .env):

   export TOGETHER_API_KEY="your-key-here"

Quick start

Build a snapshot from a Dockerfile, then run a command inside a sandbox created from it. This uses the Dockerfile in examples/read-file-python-sdk/template — an Ubuntu image with curl and git, and a /workspace/hello.txt.

1. Build the snapshot. The build runs on Together's image-builder service, so no local Docker is needed:

together-sandbox snapshot create \
  --context examples/read-file-python-sdk/template \
  --alias quickstart@v1

2. Run a command in it. sandbox run creates a sandbox from the snapshot, runs the command, and with --rm tears it down afterwards. A leading @ resolves the reference as an alias:

together-sandbox sandbox run @quickstart@v1 --rm -- uname -a

Or keep the sandbox and exec into it repeatedly:

SANDBOX_ID=$(together-sandbox sandbox create @quickstart@v1 | awk '{print $3}')

together-sandbox sandbox exec run "$SANDBOX_ID" -- uname -a
together-sandbox sandbox exec run "$SANDBOX_ID" -it -- bash   # interactive shell

together-sandbox sandbox terminate "$SANDBOX_ID"

Sandboxes are not reaped automatically unless you pass --rm or a --ttl, so terminate what you start — together-sandbox sandbox list shows what is still running. Every command group also accepts its plural form (sandboxes, snapshots, execs).

Full command reference: CLI docs.

Documentation

The canonical docs live in docs/ and are the single source of truth:

• Sandboxes and Snapshots
• Harbor Integration Guide
• Tinker + Harbor recipe
• CLI
• TypeScript SDK
• Python SDK

Bundled per-SDK docs

Each published SDK ships a copy of the docs it needs (its own SDK reference, the CLI reference, and the sandboxes/snapshots concepts) plus a top-level LLMS.md guide. They land inside the npm tarball and the Python wheel so agents and tools that introspect installed packages can discover them without hitting the network:

Package	After install, docs live at
together-sandbox (npm)	node_modules/together-sandbox/{LLMS.md,docs/}
together-sandbox (pip)	site-packages/together_sandbox/{LLMS.md,docs/}

generate.sh copies the relevant subset of docs/ into each SDK package and renders LLMS.md from LLMS-template.md with per-package substitutions.

Generated outputs (together-sandbox-*/docs/ and together-sandbox-*/LLMS.md) are git-ignored. Edit the source in docs/ and LLMS-template.md — never the generated copies.

Development

Regenerating clients

If the OpenAPI specs change, regenerate all clients from the repo root:

bash generate.sh

Release Process

Releases are fully automated via release-please — no manual tagging or version bumping required.

How it works

1. Merge PRs to main using Conventional Commits — the commit type determines what kind of release is created:

   • feat: → minor version bump
   • fix: → patch version bump
   • feat!: / BREAKING CHANGE: → major version bump
   • chore:, docs:, etc. → no release

2. release-please opens a "Release PR" automatically, accumulating changes and updating CHANGELOG.md plus all three version files in sync:

   • together-sandbox-typescript/package.json
   • together-sandbox-cli/package.json
   • together-sandbox-python/pyproject.toml

3. Merge the Release PR → release-please creates the GitHub Release and tag automatically.

4. Three publish jobs fan out in parallel, all gated on the release-please tag:

   • build-and-upload — compiles CLI binaries for all 5 platforms (darwin arm64/x64, linux x64/arm64, windows x64) and attaches them to the GitHub Release.
   • publish-npm — regenerates SDK clients, builds the TypeScript SDK, and runs npm publish to publish together-sandbox to npm using OIDC trusted publishing (no token).
   • publish-pypi — regenerates SDK clients, runs python -m build, and publishes together-sandbox to PyPI using OIDC trusted publishing (no token).

   Both publish jobs run inside protected GitHub Environments (npm and pypi) so deploys are restricted to main.

The only human action required is keeping commits conventional and merging the Release PR when ready to ship.