What is ParaSpace?

ParaSpace runs each task in a local, unprivileged system container with its own clone, services, bridge IP, and https://<name>.<domain> URL. Incus runs the containers, and Caddy routes requests from the host. Your repository's .paraspace/ directory defines workspace setup.

Where to start

I want to try it.

• Install ParaSpace to prepare your machine
• Use a ParaSpace project on repos that already have .paraspace/
• Running coding agents in parallel
• Why ParaSpace explains the approach
• How it works explains the architecture

I want to add ParaSpace to my repo.

• Add ParaSpace to a project covers initial setup
• Layers explains reusable setup components
• Cookbook has recipes for common project requirements
• Prior art compares alternative approaches

Something is broken. Troubleshooting starts at para doctor and explains what its checks mean.

Reference

• Commands covers the CLI, project commands, and shell completion.
• The env file lists every key para reads from a project's .paraspace/env.
• Hooks defines the provision/boot/image-build contract and the environment para injects.
• Hook points explains how to define and call custom hooks, including hooks implemented by several layers.
• Layers covers layer directories, the stack file, para add, and customizing a packaged layer.
• Publishing plugins is for authors who want to ship layers as an npm package (paraspace-plugin-*).
• The image contract says what a base image must provide, and how para image build builds one.
• Workspace URLs covers dropping the :8443, using your own domain, and trusting the local CA.
• Shared authentication is how you sign in once per project (the VCS key, gh, agent sessions, API tokens).
• Contract versioning explains how the para↔project interface is versioned, and what breaks on a bump.
• Internals covers self-describing workspaces, the shared volume, machine-global names, and where state lives.