opsen.mdx

title	opsen
description	Configure VibeKit with an opsen sandbox

opsen runs agent sandboxes and proxies their model calls, so machine, model and tool spend land under one task id. You can read more about it here.

Installation

First, install the opsen provider package:

npm install @vibe-kit/opsen

How to use

To use opsen with VibeKit, you need to configure opsen when creating a new VibeKit instance. You can get your API key from the opsen dashboard.

Using the provider directly

import { VibeKit } from "@vibe-kit/sdk";
import { createOpsenProvider } from "@vibe-kit/opsen";

const opsenProvider = createOpsenProvider({
  apiKey: process.env.OPSEN_API_KEY!,
  taskId: "code-review",   // Groups this agent's spend
  budgetUsd: 2.0,          // Hard cap, enforced mid-run
});

const vibeKit = new VibeKit()
  .withAgent({
    type: "grok",
    provider: "xai",
    apiKey: process.env.XAI_API_KEY!,
    model: "grok-4",
  })
  .withSandbox(opsenProvider);

// Generate code
const result = await vibeKit.generateCode({
  prompt: "Create a simple web server",
  mode: "ask"
});

// Clean up
await vibeKit.kill();

Cost attribution

VibeKit takes the model provider and key separately from the sandbox, so a team running an agent today holds two bills with no shared identifier between them. opsen sits in both paths:

await instance.cost();
// { total_usd: 0.41, compute_usd: 0.02, tokens_usd: 0.39,
//   calls: 34, task_id: "code-review" }

budgetUsd is a ceiling enforced during the run — an agent that would cross it is refused mid-flight rather than found on an invoice.

The agent type is recorded as a label when the session starts, so "which agent cost what" stays answerable across grok, claude, codex, gemini and opencode.

Configuration

Option	Default	Description
apiKey	—	Required. From opsen.dev/keys
taskId	vibekit-{agent}	Groups this agent's spend
budgetUsd	none	Hard cap, enforced mid-run
labels	{}	Arbitrary tags to group spend by
runtime	auto	auto, e2b, modal, or your own machines
baseUrl	https://opsen.dev	For self-hosted deployments

getHost

Port exposure depends on the runtime underneath. It works on E2B, works on Modal when the port was declared at sandbox creation, and throws with a message naming the limitation where unavailable — rather than returning a URL that does not answer.

ENV variables and secrets

You can use environment variables for your opsen configuration:

OPSEN_API_KEY=your_opsen_api_key_here

Then reference them in your code:

const opsenProvider = createOpsenProvider({
  apiKey: process.env.OPSEN_API_KEY!,
  taskId: "code-review",
});