Workspaces

Workspaces let you pre-configure the sandbox environment with files, dependencies, and settings. This is useful for:

Providing context (documentation, code, data files)
Pre-installing dependencies
Setting up configuration files
Creating custom development environments

How Workspaces Work

Deploy

Use the Chucky CLI to deploy your workspace files to the cloud

Session Start

When a session starts, the workspace is extracted to /workspace/project

Access

Claude and tools can read/write files in the workspace directory

Deploying Workspaces with the CLI

Installation

Install the Chucky CLI globally:

npm install -g @chucky.cloud/cli

Authentication

chucky login

Or set the environment variable:

export CHUCKY_API_KEY=ak_live_xxxxx

Initialize Project

In your workspace directory, initialize a Chucky project:

cd my-workspace
chucky init

This creates a .chucky.json configuration file:

{
  "projectId": "proj_xxxxx",
  "projectName": "my-project",
  "folder": ".",
  "hmacKey": "your-hmac-secret"
}

Deploy

Deploy your workspace to the cloud:

chucky deploy

The CLI automatically:

Creates a compressed archive of your files
Excludes unnecessary files (node_modules, .git, build artifacts, etc.)
Uploads to Chucky’s cloud storage
Provides a test token for immediate use

Automatic Exclusions

The CLI automatically excludes these patterns when creating the archive:

node_modules/**
.git/**
.env, .env.*
*.log
.DS_Store, Thumbs.db
dist/**, build/**, .next/**, .nuxt/**
coverage/**, .cache/**
*.tgz, *.tar.gz
.chucky.json

CI/CD Integration

GitHub Actions

The chucky init command can generate a GitHub Actions workflow for automatic deployments:

# .github/workflows/chucky-deploy.yml
name: Deploy to Chucky

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @chucky.cloud/cli
      - run: chucky deploy
        env:
          CHUCKY_API_KEY: ${{ secrets.CHUCKY_API_KEY }}

Add your CHUCKY_API_KEY to your repository secrets.

CLI Commands Reference

Command	Description
`chucky login`	Authenticate with your API key
`chucky init`	Initialize a new project in current directory
`chucky deploy`	Deploy workspace to the cloud
`chucky list`	List all your projects
`chucky keys`	Show HMAC key for current project
`chucky config anthropic`	Set Anthropic API key for project
`chucky delete`	Delete a project

Workspace Contents

Common things to include:

Documentation

workspace/
├── docs/
│   ├── README.md
│   ├── API.md
│   └── ARCHITECTURE.md

Code Context

workspace/
├── src/
│   ├── index.ts
│   ├── utils.ts
│   └── types.ts
├── package.json
└── tsconfig.json

Data Files

workspace/
├── data/
│   ├── products.json
│   ├── users.csv
│   └── config.yaml

Templates

workspace/
├── templates/
│   ├── component.tsx
│   ├── api-route.ts
│   └── test.spec.ts

Alternative: Git Repositories

Instead of deploying a workspace, you can configure a Git repository to be cloned on each session:

In Portal Settings

Configure Git in your project settings at app.chucky.cloud:

Option	Description
`url`	Repository URL (HTTPS)
`ref`	Branch, tag, or commit (default: `main`)
`token`	Personal access token for private repos
`depth`	Shallow clone depth (default: 1)

Benefits of Git

Always up-to-date: Latest code on each session
Branch selection: Test different branches
No manual deploys: Automatic syncing

Git clone happens on every session start, so it adds latency. For static content, deployed workspaces are faster.

Accessing Workspace Files

In Custom Tools

const readFileTool = tool(
  'read_project_file',
  'Read a file from the project workspace',
  {
    type: 'object',
    properties: {
      path: { type: 'string', description: 'File path relative to workspace' },
    },
    required: ['path'],
  },
  async ({ path }) => {
    // Files are at /workspace/project/
    const fullPath = `/workspace/project/${path}`;
    const content = await fs.readFile(fullPath, 'utf-8');
    return textResult(content);
  }
);

Claude Access

Claude can reference workspace files using built-in tools:

User: "What's in the README?"
Claude: [Uses Read tool to read /workspace/project/README.md]
Claude: "The README contains..."

Session Persistence

Session state is saved separately from the workspace:

Workspace: Shared across all users (read-only base)
Session state: Per-user, persists between sessions

Session files are stored at:

/root/.claude/ - Claude’s memory and context
/root/.claude.json - Session configuration

Best Practices

Keep workspaces small

Large workspaces increase session startup time. Only include files Claude needs.Do include:

Documentation
Type definitions
Configuration files
Small code samples

Don’t include:

node_modules (auto-excluded)
Build artifacts (auto-excluded)
Large binary files
Test fixtures

Use .chuckyignore

Create a .chuckyignore file for project-specific exclusions (same syntax as .gitignore):

# Custom exclusions
secrets/
*.pem
large-data/

Include a manifest

Add a file describing the workspace contents:

// workspace.json
{
  "name": "my-project",
  "description": "E-commerce API codebase",
  "version": "1.0.0",
  "structure": {
    "src/": "Source code",
    "docs/": "Documentation",
    "data/": "Sample data files"
  }
}

Automate with CI/CD

Set up automatic deployments on push to main branch. This ensures Claude always has the latest context.

Example: Documentation Bot

# Create workspace directory
mkdir doc-workspace
cd doc-workspace

# Copy documentation
cp -r ../docs/* .

# Add context file
cat > CONTEXT.md << 'EOF'
# Documentation Assistant Context

You are a documentation assistant for the Acme API.

## Available Documentation
- `api/` - API reference docs
- `guides/` - Tutorial guides
- `examples/` - Code examples

## Your Role
- Answer questions about the API
- Provide code examples
- Explain concepts from the docs
EOF

# Initialize and deploy
chucky init
chucky deploy

Example: Code Review Bot

mkdir review-workspace
cd review-workspace

# Copy codebase (without node_modules, .git - auto-excluded)
cp -r ../my-codebase/* .

# Add review guidelines
cat > REVIEW_GUIDELINES.md << 'EOF'
# Code Review Guidelines

When reviewing code, check for:

1. **Correctness**: Does the code do what it's supposed to?
2. **Security**: Are there any security vulnerabilities?
3. **Performance**: Are there obvious performance issues?
4. **Style**: Does it follow project conventions?
5. **Tests**: Are there adequate tests?

## Project Conventions
- Use TypeScript strict mode
- Prefer async/await over callbacks
- Use descriptive variable names
EOF

# Initialize and deploy
chucky init
chucky deploy

Getting Started

Guides

CLI

Use Cases

Advanced

Concepts

Configure sandbox environments

Workspaces

How Workspaces Work

Deploying Workspaces with the CLI

Installation

Authentication

Initialize Project

Deploy

Automatic Exclusions

CI/CD Integration

GitHub Actions

CLI Commands Reference

Workspace Contents

Documentation

Code Context

Data Files

Templates

Alternative: Git Repositories

In Portal Settings

Benefits of Git

Accessing Workspace Files

In Custom Tools

Claude Access

Session Persistence

Best Practices

Example: Documentation Bot

Example: Code Review Bot

​Workspaces

​How Workspaces Work

​Deploying Workspaces with the CLI

​Installation

​Authentication

​Initialize Project

​Deploy

​Automatic Exclusions

​CI/CD Integration

​GitHub Actions

​CLI Commands Reference

​Workspace Contents

​Documentation

​Code Context

​Data Files

​Templates

​Alternative: Git Repositories

​In Portal Settings

​Benefits of Git

​Accessing Workspace Files

​In Custom Tools

​Claude Access

​Session Persistence

​Best Practices

​Example: Documentation Bot

​Example: Code Review Bot

Workspaces

How Workspaces Work

Deploying Workspaces with the CLI

Installation

Authentication

Initialize Project

Deploy

Automatic Exclusions

CI/CD Integration

GitHub Actions

CLI Commands Reference

Workspace Contents

Documentation

Code Context

Data Files

Templates

Alternative: Git Repositories

In Portal Settings

Benefits of Git

Accessing Workspace Files

In Custom Tools

Claude Access

Session Persistence

Best Practices

Example: Documentation Bot

Example: Code Review Bot