Quick Start

This guide walks you through initializing cspace in a project and launching your first devcontainer instance.

1. Initialize your project

Navigate to your project root and run:

Terminal

cd my-project
cspace init

This creates two things:

• .cspace.json — project configuration (commit this to git)
• .cspace/ — directory for template overrides and custom scripts

cspace auto-detects your project name (from the directory name), GitHub repo (from git remote), and a two-character prefix for naming containers.

Tip

Run cspace init --full to also copy the built-in templates (Dockerfile, docker-compose files, agent prompts) into .cspace/ for customization.

2. Set up Git authentication

Before launching an instance, add a GitHub personal access token to your project:

Project root

echo 'GH_TOKEN=ghp_yourTokenHere' >> .env

This is required for git push/pull inside containers. See Git Authentication for details on creating a token with the right scopes.

3. Launch an instance

cspace up

This will:

1. Assign a planet name (mercury, venus, earth…) with deterministic port mappings
2. Build the devcontainer image (first run only)
3. Bundle and copy your repository into the container
4. Copy your git identity and .env into the container
5. Configure gh as the git credential helper
6. Launch Claude Code inside the instance

You can also specify a name or branch:

cspace up venus              # use a specific planet name
cspace up feature/my-branch  # check out a branch
cspace up --no-claude earth  # create instance without launching Claude

4. Develop

Once an instance is running, you have several ways to interact with it:

cspace ssh mercury      # shell into the instance
cspace list             # see all running instances
cspace ports mercury    # show port mappings

To run an autonomous agent against a GitHub issue:

# Write a prompt referencing the issue, then launch an instance with it
cat > /tmp/issue-prompt.txt <<'EOF'
Resolve GitHub issue #42 end-to-end. Read the issue, implement the fix,
verify with tests, and open a PR.
EOF
cspace up mars --prompt-file /tmp/issue-prompt.txt

Tip

Run cspace with no arguments to open an interactive TUI menu.

5. Clean up

When you’re done with an instance:

cspace down mercury     # destroy a single instance
cspace down --all       # destroy all instances for this project

Next steps

• Git Authentication — set up your GitHub token and understand SSO requirements
• Configuration Reference — customize ports, firewall, Claude model, and more
• CLI Reference — full command documentation