Skip to main content

​
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

1

Deploy

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

Session Start

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

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

Login with your API key (get it from app.chucky.cloud): 
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

CommandDescription
chucky loginAuthenticate with your API key
chucky initInitialize a new project in current directory
chucky deployDeploy workspace to the cloud
chucky listList all your projects
chucky keysShow HMAC key for current project
chucky config anthropicSet Anthropic API key for project
chucky deleteDelete 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:
OptionDescription
urlRepository URL (HTTPS)
refBranch, tag, or commit (default: main)
tokenPersonal access token for private repos
depthShallow 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

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
Create a .chuckyignore file for project-specific exclusions (same syntax as .gitignore):
# Custom exclusions
secrets/
*.pem
large-data/
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"
  }
}
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