tessl/npm-anthropic-ai--claude-agent-sdk

SDK for building AI agents with Claude Code's capabilities to programmatically interact with Claude and build autonomous agents that can understand codebases, edit files, and execute workflows.

Overview

Eval results

Files

Sandbox Configuration

Name: tessl/npm-anthropic-ai--claude-agent-sdk
Author: tessl

Secure execution environment with network and filesystem restrictions.

Settings

interface SandboxSettings {
  enabled?: boolean;
  autoAllowBashIfSandboxed?: boolean;
  allowUnsandboxedCommands?: boolean;
  network?: SandboxNetworkConfig;
  ignoreViolations?: Record<string, string[]>;
  enableWeakerNestedSandbox?: boolean;
  excludedCommands?: string[];
  ripgrep?: {command: string; args?: string[]};
}

interface SandboxNetworkConfig {
  allowUnixSockets?: string[];
  allowAllUnixSockets?: boolean;
  allowLocalBinding?: boolean;
  httpProxyPort?: number;
  socksProxyPort?: number;
}

Examples

Basic Sandbox

sandbox: {
  enabled: true,
  autoAllowBashIfSandboxed: true
}

Docker Support

sandbox: {
  enabled: true,
  network: {
    allowUnixSockets: ['/var/run/docker.sock']
  }
}

Network Proxying

sandbox: {
  enabled: true,
  network: {
    httpProxyPort: 8080,
    socksProxyPort: 1080
  }
}

Exclude Commands

sandbox: {
  enabled: true,
  excludedCommands: ['make', 'npm', 'cargo'],
  allowUnsandboxedCommands: true
}

Ignore Violations

sandbox: {
  enabled: true,
  ignoreViolations: {
    'file_access': ['/tmp/*', '/var/cache/*'],
    'network': ['*.internal.company.com']
  }
}

Custom Ripgrep

sandbox: {
  enabled: true,
  ripgrep: {
    command: '/usr/local/bin/rg',
    args: ['--hidden']
  }
}

Complete Example

const result = query({
  prompt: 'Build Docker container and run tests',
  options: {
    sandbox: {
      enabled: true,
      autoAllowBashIfSandboxed: true,

      network: {
        allowUnixSockets: ['/var/run/docker.sock'],
        allowLocalBinding: true,
        httpProxyPort: 8080
      },

      excludedCommands: ['docker', 'npm', 'node'],
      allowUnsandboxedCommands: true,

      ignoreViolations: {
        'file_access': ['/tmp/*', '~/.npm/*', '~/.docker/*']
      },

      enableWeakerNestedSandbox: true
    }
  }
});

Important Notes

Sandbox settings control sandbox behavior (enabled, auto-allow, etc.), not access restrictions.

Filesystem access: Configure via additionalDirectories and permission rules.

Network access: Configure via permission rules.

Example:

{
  // Sandbox behavior
  sandbox: {
    enabled: true,
    autoAllowBashIfSandboxed: true
  },

  // Filesystem access (separate)
  additionalDirectories: ['/allowed/path'],

  // Permission mode
  permissionMode: 'default'
}

Types

type SandboxIgnoreViolations = Record<string, string[]>;

Zod Schemas

const SandboxNetworkConfigSchema: z.ZodOptional<z.ZodObject<{
  allowUnixSockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
  allowAllUnixSockets: z.ZodOptional<z.ZodBoolean>;
  allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
  httpProxyPort: z.ZodOptional<z.ZodNumber>;
  socksProxyPort: z.ZodOptional<z.ZodNumber>;
}>>;

const SandboxSettingsSchema: z.ZodObject<{
  enabled: z.ZodOptional<z.ZodBoolean>;
  autoAllowBashIfSandboxed: z.ZodOptional<z.ZodBoolean>;
  allowUnsandboxedCommands: z.ZodOptional<z.ZodBoolean>;
  network: typeof SandboxNetworkConfigSchema;
  ignoreViolations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
  enableWeakerNestedSandbox: z.ZodOptional<z.ZodBoolean>;
  excludedCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
  ripgrep: z.ZodOptional<z.ZodObject<{
    command: z.ZodString;
    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
  }>>;
}>;

Usage:

import { SandboxSettingsSchema } from '@anthropic-ai/claude-agent-sdk';

const config = {
  enabled: true,
  network: {allowUnixSockets: ['/var/run/docker.sock']}
};

const result = SandboxSettingsSchema.safeParse(config);
if (result.success) {
  console.log('Valid:', result.data);
} else {
  console.error('Invalid:', result.error);
}

Install with Tessl CLI

npx tessl i tessl/npm-anthropic-ai--claude-agent-sdk

docs

apis