Running from source is how you contribute to Company Agents, build an adapter, or work on a plugin. If you just want to use Company Agents, install the binary; this guide is for developers.

​
Prerequisites

  • Node.js 22 or later (we use corepack for pnpm)
  • pnpm 9 (installed via corepack)
  • Git (obviously)
  • A POSIX shell (bash, zsh, fish, or the Git Bash that ships with Git for Windows)
  • About 4 GB of free RAM to run the full stack comfortably
Optional:
  • Docker if you want to run the Postgres shape locally instead of the in-process PGlite shape

​
Clone and install

git clone https://github.com/company-agents/company-agents
cd company-agents
corepack enable
pnpm install
The install takes a minute or two on a fast connection. If it hangs, check that pnpm is on your PATH (pnpm -v should print the version).

​
The monorepo layout

company-agents/
├── apps/
│   ├── desktop/        # Electron shell (desktop builds)
│   ├── dashboard/      # React 19 + Vite UI
│   └── cli/            # company-agents CLI
├── services/
│   ├── orchestrator/   # The task scheduler, lease manager, health monitor
│   └── mcp-server/     # HTTP SSE MCP server for agent tools
├── packages/
│   ├── db/             # Drizzle schema and PGlite adapter
│   ├── shared/         # Shared types and utilities
│   ├── adapters/       # Per-CLI agent adapters
│   └── plugins/        # Plugin runtime
├── docs/               # This documentation site
└── marketing/web/      # Marketing site (Next.js)
You will spend most of your time in services/orchestrator/, packages/adapters/, or apps/dashboard/, depending on what you are working on.

​
Running the stack

The whole stack is one command: 
pnpm dev
This starts:
  • The orchestrator on :3100
  • The dashboard on :3101
  • The MCP server on :4200
  • A PGlite instance backed by ~/.company-agents/instances/default/db/
Open the dashboard at http://localhost:3101 and you should see the “Create your first company” screen. If you want to run only one piece (say, you are working on the dashboard and you already have the orchestrator running from a previous session), use filters: 
pnpm --filter @company-agents/dashboard dev
pnpm --filter @company-agents/orchestrator dev

​
Environment variables

For local development, a .env.local at the repo root is read by every package. The defaults are sensible; the ones you might actually want to override: 
# Where the instance data lives
COMPANY_AGENTS_HOME=~/.company-agents/instances/default

# Optional: use a real Postgres instead of PGlite
DATABASE_URL=postgres://company-agents:company-agents@localhost:5432/company-agents

# Master key for secret encryption. Defaults to a dev key in
# development. NEVER use the default in production.
MASTER_KEY_PATH=~/.company-agents/instances/default/secrets/master.key

# Pick your primary LLM provider. Dynamic via the Vercel AI SDK.
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-...
See Environment variables for the full list.

​
Using a real Postgres instead of PGlite

PGlite is fine for development but slow on large runs. To swap in real Postgres: 
docker run -d --name company-agents-pg \
  -e POSTGRES_USER=company-agents \
  -e POSTGRES_PASSWORD=company-agents \
  -e POSTGRES_DB=company-agents \
  -p 5432:5432 \
  postgres:16

export DATABASE_URL=postgres://company-agents:company-agents@localhost:5432/company-agents
pnpm db:migrate
pnpm dev
The Drizzle migrator handles the schema. If you pull a commit that adds a migration, run pnpm db:migrate before restarting the stack.

​
Tests

pnpm test           # all tests across the monorepo
pnpm test:unit      # unit only
pnpm test:e2e       # end-to-end (boots a real stack)
The E2E suite runs against a throwaway PGlite instance and takes a few minutes. CI runs both on every PR.

​
Building an adapter locally

Adapters live in packages/adapters/. To build a new one: 
pnpm --filter @company-agents/adapters create-adapter my-cli
The scaffolder writes a new package with a minimal AdapterBase implementation, wires it into the registry, and adds a test skeleton. See Creating an adapter for the full shape.

​
Debugging

The orchestrator logs to stdout in development. To get a more detailed log: 
LOG_LEVEL=debug pnpm dev
For the dashboard, the React DevTools work as usual. For the orchestrator, --inspect works: 
pnpm --filter @company-agents/orchestrator dev:inspect
Then attach a Node debugger at the printed URL.

​
Hot reload caveats

The dashboard hot-reloads everything. The orchestrator hot-reloads most things but not the database schema or the MCP server tool registrations. If you change a schema file, run pnpm db:migrate and restart the orchestrator. If you change an MCP tool signature, restart the MCP server.

​
Next

  • Docker if you want a single-command deployment instead of the source checkout.
  • Database for the database layer in more depth.
  • Environment variables for everything you can configure.