Skip to main content

Quickstart Guide

Get Visus Agent Sandbox running in under 5 minutes.

Prerequisites​

  • Node.js >= 20 (LTS)
  • npm >= 10

Installation​

Visus Agent Sandbox is published as an npm package. You can run it directly with npx without installing:

npx visus-sandbox demo

This runs a self-contained demo showing Visus Agent Sandbox blocking a production database deletion.

Demo GIF

Expected Output​

Visus Agent Sandbox v0.1.0 — Pre-Execution Simulation

Running demo scenario: AI agent attempts to delete a production RDS instance

  Agent Action:
    Service:    rds
    Operation:  DeleteDBInstance
    Resource:   arn:aws:rds:us-east-1:123456789012:db:prod-customer-data
    Tags:       Environment=production, Tier=critical

  IPI Check:     CLEAN  (score: 0.00)
  Simulation:    LOCAL MOCK

  Policy Evaluation:
    ✖  SE-001  CRITICAL  Block production database deletion
               Matched: service=rds, operation=DeleteDBInstance, tag Environment=production

  Decision:      BLOCKED
  Rule:          SE-001
  Log entry:     ~/.visus-sandbox/audit.ndjson  [HMAC signed]

Action was blocked before reaching infrastructure.
Simulation took 12ms.

Initialize a Policy File​

Create a visus-sandbox.policy.yaml file in your project directory:

npx visus-sandbox init

This generates a starter policy file:

version: "1.0"
name: "Default Visus Agent Sandbox Policy"
rules:
  - id: SE-001
    name: Block production database deletion
    severity: CRITICAL
    action: BLOCK
    match:
      service: rds
      operation: DeleteDBInstance
      resource_tags:
        Environment: production

  - id: SE-002
    name: Require approval for IAM policy changes
    severity: HIGH
    action: REQUIRE_APPROVAL
    match:
      service: iam
      operation: [AttachUserPolicy, AttachRolePolicy, PutUserPolicy, PutRolePolicy]

  - id: SE-003
    name: Warn on S3 public access
    severity: MEDIUM
    action: WARN
    match:
      service: s3
      operation: PutBucketAcl
      parameters:
        ACL: [public-read, public-read-write]

Integrate with Your Agent Framework​

MCP Integration​

import { createShadowExecutorMiddleware } from '@visus-mcp/agent-sandbox-sdk/mcp';

const shadowMiddleware = createShadowExecutorMiddleware({
  policyPath: './visus-sandbox.policy.yaml',
  logPath: '~/.visus-sandbox/audit.ndjson',
  logSecret: process.env.VISUS_SANDBOX_LOG_SECRET,
  enableIPIDetection: true,
});

// Wrap your MCP server with Visus Agent Sandbox
server.use(shadowMiddleware);

Claude Code Integration​

Create ~/.visus-sandbox/claude-code-config.json:

{
  "enabled": true,
  "policy_path": "./visus-sandbox.policy.yaml",
  "log_path": "~/.visus-sandbox/audit.ndjson",
  "simulation_mode": "local",
  "enable_ipi_detection": true
}

Visus Agent Sandbox automatically wraps Claude Code's MCP server via middleware injection.

LangGraph Integration​

import { createShadowExecutorTool } from '@visus-mcp/agent-sandbox-sdk/langgraph';

const tools = [
  createShadowExecutorTool({
    name: 'aws_rds_delete_db_instance',
    policyPath: './visus-sandbox.policy.yaml',
    baseHandler: async (params) => {
      // Original tool logic
    }
  })
];

Verify Audit Log Integrity​

Visus Agent Sandbox signs all audit log entries with HMAC-SHA-256. Verify log integrity:

export VISUS_SANDBOX_LOG_SECRET="your-secret-key"
npx visus-sandbox verify-log

Expected output:

Visus Agent Sandbox - Audit Log Verification
=========================================

Log file: /Users/you/.visus-sandbox/audit.ndjson

✓ Log integrity verified
  Total entries: 42
  All HMAC signatures valid

Next Steps​

Estimated Completion Time​

This quickstart should take 3-4 minutes from start to finish.

If you encountered issues, please check the FAQ or open an issue on GitHub.