> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chucky.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure sandbox environments

> Pre-configure sandbox environments with custom files and dependencies

# 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

<Steps>
  <Step title="Deploy">
    Use the Chucky CLI to deploy your workspace files to the cloud
  </Step>

  <Step title="Session Start">
    When a session starts, the workspace is extracted to `/workspace/project`
  </Step>

  <Step title="Access">
    Claude and tools can read/write files in the workspace directory
  </Step>
</Steps>

## Deploying Workspaces with the CLI

### Installation

Install the Chucky CLI globally:

```bash theme={null}
npm install -g @chucky.cloud/cli
```

### Authentication

Login with your API key (get it from [app.chucky.cloud](https://app.chucky.cloud)):

```bash theme={null}
chucky login
```

Or set the environment variable:

```bash theme={null}
export CHUCKY_API_KEY=ak_live_xxxxx
```

### Initialize Project

In your workspace directory, initialize a Chucky project:

```bash theme={null}
cd my-workspace
chucky init
```

This creates a `.chucky.json` configuration file:

```json theme={null}
{
  "projectId": "proj_xxxxx",
  "projectName": "my-project",
  "folder": ".",
  "hmacKey": "your-hmac-secret"
}
```

### Deploy

Deploy your workspace to the cloud:

```bash theme={null}
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:

```yaml theme={null}
# .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](https://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

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

## Accessing Workspace Files

### In Custom Tools

```typescript theme={null}
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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Use .chuckyignore">
    Create a `.chuckyignore` file for project-specific exclusions (same syntax as `.gitignore`):

    ```
    # Custom exclusions
    secrets/
    *.pem
    large-data/
    ```
  </Accordion>

  <Accordion title="Include a manifest">
    Add a file describing the workspace contents:

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

  <Accordion title="Automate with CI/CD">
    Set up automatic deployments on push to main branch. This ensures Claude always has the latest context.
  </Accordion>
</AccordionGroup>

## Example: Documentation Bot

```bash theme={null}
# 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

```bash theme={null}
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
```