Skip to main content
Use this guide when your framework is not listed, or when you have a custom planner/executor that needs an isolated Linux workspace. There are two supported shapes:
  • Use direct sandbox APIs when your application needs fine-grained command, file, PTY, SSH, desktop, or lifecycle control.
  • Use Agent Deployments when you want Nullspace to deploy a named job or service from a local project and operate it over time.

​
Integration Shape

  1. Create a sandbox from base or a custom template.
  2. Pass only the credentials and configuration the agent needs through envs.
  3. Clone or upload workspace inputs into /workspace.
  4. Run agent steps with sandbox.commands, sandbox.files, sandbox.git, or framework-specific tools.
  5. Collect outputs, artifacts, diffs, logs, or preview URLs.
  6. Hibernate for resumable sandboxes or destroy for one-shot tasks.
from nullspace import Sandbox

with Sandbox.create(
    template="base",
    envs={"AGENT_RUN_ID": "run_123"},
    timeout=900,
) as sandbox:
    sandbox.git.clone("https://github.com/example/project.git", "/workspace/project")
    result = sandbox.commands.run(
        "./your-agent --task 'inspect the project'",
        shell=True,
        cwd="/workspace/project",
        timeout=900,
    )
    print(result.stdout)

​
When To Use Agent Deployments

Use Agent Deployments when you want Nullspace to deploy a named job or service from your local project, manage runs or service instances, retain backing sandboxes for debugging, and collect logs and outputs through the deployment API. Keep using direct sandbox APIs when your app needs fine-grained control over every sandbox command, upload, download, PTY session, SSH session, desktop interaction, or lifecycle action.

​
Template Strategy

  • Use base for one-off command and file tasks.
  • Build a custom template when your agent repeatedly installs the same tools, package managers, browsers, or language runtimes.
  • Use start-ready commands for services the agent expects to be available immediately.

​
Cleanup Strategy

  • Destroy short-lived sandboxes with sandbox.kill() or a context manager.
  • Use on_timeout="pause", auto_resume=True for per-user workspaces.
  • Use Fork to test multiple plans from a shared warm setup.

​
State And Sessions

Nullspace run IDs are not conversation session IDs. Framework session, thread, checkpoint, or flow state stays app-owned. Use volumes, retained sandboxes, hibernate/auto-resume, or an external database for durable conversation state, repo state, generated artifacts, or framework checkpoint storage.