---
name: bijection-tenki
description: "Evaluate and integrate the Tenki component with Bijection."
---

# Tenki

Tenki Sandboxes for Bijection: cloud sandboxes for AI agents, with live state in your Bijection tables.

- Package: @bijectionhq/tenki
- Category: Sandboxes
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/tenki/tree/eacb1453ef98f3ed5b9e5c871ce1d27a1f867801
- Upstream: https://github.com/LuxorLabs/tenki-convex/tree/81a970851f4c0a00c34d8b6ecaae4836bd66397b
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/tenki

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/tenki.git
cd tenki
git checkout eacb1453ef98f3ed5b9e5c871ce1d27a1f867801
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @tenkicloud/convex. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Tenki Sandboxes. Follow the installation and configuration steps exactly.

# Tenki Sandboxes

## Instructions

Use Tenki Sandboxes to run full microvm sandboxes from convex actions with live state sync, giving each user or ai agent isolated shell, file, and network access. This Convex component integrates directly with your backend.

### Installation

```bash
npm install @tenkicloud/convex
```

Current npm version: `@tenkicloud/convex@0.1.1`

### Capabilities

- Provision per-user or per-agent microVMs that boot in about a second and store lifecycle state directly in Convex tables for real-time UI subscriptions.
- Execute shell commands, manage background processes, read and write files, and expose public preview URLs from Convex actions without managing infrastructure.
- Pause and resume sandboxes with memory intact, take snapshots, and fork sandboxes so agents or users can branch from a known state.
- Enforce multi-tenant isolation server-side by keying sandboxes to authenticated user IDs, with crash-safe create semantics that handle retries and concurrent calls.

## Examples

### how to give each user their own cloud VM in a Convex app

Tenki Sandboxes provides a Convex component that provisions a microVM per user, keyed by ownerId and a string key. Calling tenki.create() from a Convex action creates the sandbox if it does not exist and resumes it if paused, with idempotent semantics safe to retry. The sandbox phase is stored in a Convex table, so your frontend can subscribe to live status updates using useQuery.

### run shell commands from Convex actions for AI agents

Tenki Sandboxes exposes tenki.exec() for running a command and waiting for output, and tenki.spawn() for starting a background process that persists across action boundaries and across pause and resume cycles. Both run inside an isolated microVM, so each agent gets its own execution environment. The API key stays in a Convex environment variable and never reaches the client.

### how to snapshot and fork a sandbox in Convex for AI agent branching

Tenki Sandboxes provides tenki.snapshot() to capture a sandbox's disk state and tenki.fork() to create a new sandbox from a snapshot of an existing one. After a fork, the two sandboxes run independently. This lets AI agent workflows branch from a known checkpoint without duplicating setup work.

### real-time sandbox status updates in Convex UI

The Tenki component writes sandbox lifecycle state to a Convex table, so phases like provisioning, ready, pausing, paused, resuming, and terminated are immediately queryable. A Convex query using components.tenki.sandboxes.get can be subscribed to with useQuery, giving the UI live updates without polling.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Tenki Sandboxes is not needed

## Troubleshooting

**How does Tenki Sandboxes handle concurrent create calls for the same user?**

Tenki Sandboxes makes create idempotent: calling tenki.create() concurrently for the same ownerId and key always results in a single sandbox. If a concurrent create fails mid-flight, the next call adopts the tagged session rather than creating a duplicate. This means it is safe to retry creates from Convex actions without risk of provisioning multiple sandboxes for the same identity.

**How does multi-tenant isolation work in Tenki Sandboxes?**

Each sandbox is keyed by a combination of ownerId and a string key. The README explicitly states that ownerId is the only thing separating tenants and must always be derived from ctx.auth, never from client input. Typically you pass the authenticated user ID returned by getAuthUserId as the ownerId.

**How do I limit how many sandboxes can run simultaneously?**

Tenki Sandboxes accepts a maxActiveSandboxes option when constructing the Tenki instance: new Tenki(components.tenki, { maxActiveSandboxes: 20 }). Once the limit is reached, any attempt to start or resume a sandbox throws a capacity_exceeded error. The check runs inside the same Convex transaction that reserves the sandbox row, so concurrent creates and forks cannot exceed the limit.

**What happens when a Tenki sandbox reaches its time limit?**

Tenki pauses the sandbox at its maxDurationMs deadline and retains it for the configured pause retention period, defaulting to 7 days. The Convex row keeps the last known phase until a refresh, reconcile, or the next create call syncs it. Calling tenki.create() on a paused sandbox resumes it and starts a new duration window of the same length, so maxDurationMs bounds each run rather than the sandbox's total lifetime.

**Does Tenki Sandboxes require a specific Convex runtime for actions?**

Yes. The Tenki SDK depends on Node.js, so the action file that calls Tenki methods must include the 'use node' directive at the top. Queries that read sandbox state from the Convex table do not require Node.js and run in the default Convex runtime, which means UI subscriptions work without any special configuration.

## Resources

- [npm package](https://www.npmjs.com/package/%40tenkicloud%2Fconvex)
- [GitHub repository](https://github.com/LuxorLabs/tenki-convex)
- [Live demo](https://github.com/LuxorLabs/tenki-convex/tree/main/example)
- [Convex Components Directory](https://www.convex.dev/components/tenkicloud/convex)
- [Convex documentation](https://docs.convex.dev)