Your team.
Up and running.

01 / BEFORE YOU START

What you need

AI Employees is source code you run on your computer or infrastructure. The web app manages assignments; a separate worker does the work.

1. Download your purchased package and extract it into its own folder. Core and Complete contain different employee rosters; use the roles included in your package.
2. Install Node.js 22.13 or newer and pnpm 10.15.1 (the version pinned in package.json). Open a terminal in the folder containing package.json.
3. Have an agent-capable account ready: Claude Code on your machine, Codex, or an Anthropic, OpenAI or OpenRouter API key. Provider usage is billed by that provider.
4. For research, also connect a web-capable route: Brave Search, OpenRouter or Codex. A Brave key supplies search, not the agent that writes your brief.

node --version
pnpm --version

An existing installation needs an upgrade, not fresh setup. Back up your code, configuration, database, media and worker state first.

02 / INSTALL

Install on Windows or macOS

Use PowerShell on Windows or Terminal on macOS. The project commands are the same; no WSL is required by these instructions.

1. Run pnpm install --frozen-lockfile. Keep pnpm-lock.yaml so the installed dependency versions match the release.
2. For a fresh installation, run pnpm run setup:local. It creates private local settings, a stable worker identity and an encryption key automatically. Keep .env.local backed up; never share it or replace its key after saving provider accounts.
3. Run pnpm dev:stack. It checks required tools, chooses a free local port, starts the app, waits for it to respond, then starts your worker at the same address. Leave this terminal open.
4. Open the exact URL printed by the launcher. In Get your first result, choose writing, research or improving existing writing. Tell us about your business, your audience and what you need. The app prepares the brief and selects an employee.
5. If setup:local says configuration already exists, it leaves every setting and encryption key untouched. For an existing installation use the upgrade guide; for an incomplete manual setup, review SETUP.md and the startup error.

pnpm install --frozen-lockfile
pnpm run setup:local
pnpm dev:stack

These setup commands require a release containing setup:local. Local database and media storage live in .wrangler. Keep that folder and .env.local; deleting them is not a startup fix. Local auth is only for your own computer.

03 / VERIFY

Check that both parts are running

A working homepage proves only the web app is running. Employees also need a live worker.

1. Open /api/health at the URL printed by dev:stack. It should return ok: true and the installed version.
2. Prepare your first brief in HQ. The app checks your account and the worker before enabling Start. A coworker’s private worker does not count as your worker.
3. If assignments remain queued, confirm the worker is running, CONTROL_PLANE_URL points to this app, and your local worker belongs to the task owner.
4. With local auth enabled, dev:stack derives the owner member ID. For a separately started or hosted local worker, set WORKER_OWNER_MEMBER_ID to the authenticated member ID, not an email address.
5. If either process exits unexpectedly, the launcher stops the other one and prints the error. Fix that error and restart pnpm dev:stack. Ctrl+C stops both processes.

Closing dev:stack stops local processing. Restart it from the same installation folder to use the same data.

04 / PROVIDERS

Connect your AI accounts

Open Settings → Providers & routing. App sign-in and provider sign-in are separate.

1. For an API provider, choose the provider, paste your own key into its connection form and save. Wait for connected / verified status; a pending card is not proof of usable access.
2. For Claude Code, install and sign in to the Claude CLI yourself on the worker machine, then connect Claude Code (your machine). This route requires your own local worker.
3. For Codex subscription, ensure codex --version succeeds, click Connect and complete the displayed device-login instructions yourself. Keep the worker running while authorizing.
4. For Theo or another research role, connect Brave Search, OpenRouter or Codex for web research. In routing settings, ensure the task owner can access the selected agent and web routes.
5. Add image/video provider keys only if your assignment needs those capabilities. A text connection alone does not grant every image or video service.

Codex sessions live under the persistent worker state directory and are assigned to a worker identity. Keep WORKER_ID stable; reconnect if you deliberately move to another worker.

05 / FIRST ASSIGNMENT

Get your first useful result

Use your own business and a small, useful outcome. You do not need to choose from the employee roster or write a detailed prompt.

1. In HQ, choose Write something, Research something, or Improve existing writing under Get your first result. Writing is the simplest start; research also needs a connected web provider.
2. Answer three questions: what your business or project does, who the result is for, and what you need. For improvements, paste the existing writing. Click Prepare my brief.
3. Review the prepared brief, selected employee and $5 task budget cap. Edit your answers if needed. Nothing has been dispatched yet.
4. If prompted, connect your AI account in Settings. Complete sign-in yourself, then click Return to my first result. Your answers and assignment link are kept in this browser through navigation, reload and reopening; they are not shared across devices. Keep pnpm dev:stack running.
5. Click Start with Maya or Start with Theo. If the connection is interrupted, use Retry safely to recover the same assignment. The employee produces a saved draft; HQ shows the result when it is ready. You can also open the assignment for live activity or errors. A failed run shows its error and Retry this assignment; correct missing accounts or setup before retrying.
6. Read the result, then Copy result or Download. Use Make it shorter or type a revision such as “Make the tone warmer.” Revisions continue the same assignment and use provider budget. Open editor for full editing controls.
7. When you are ready, choose Create another result or Use the full workspace. Return to HQ in the same browser to resume your guided brief or result. Completed work also remains available in Assignments.

Your first win is a useful saved result you have opened and reviewed. A connected account or a queued task alone does not prove it worked.

06 / RESEARCH

Get a useful sourced research brief

Theo needs both an agent and live web access. Define the questions, audience, source constraints and intended decision.

1. Try: “Research the public pages at https://example.com and relevant primary sources. Produce a sourced content brief with audience questions, supported findings, gaps and recommended topics. Distinguish facts from inferences.” Replace the example URL with the actual site.
2. Theo searches, captures at least two distinct readable sources, records cited findings and saves a report linked to that evidence. Search snippets alone do not count as captured sources.
3. Open the research output and check source URLs, dates, claims and gaps. A source being captured does not make every statement in it reliable.
4. If a site is login-only, blocks automated access, or provides too little readable text, supply another public source or narrow the task. Do not ask the employee to invent missing evidence.
5. If the Task Room shows a failed tool, record its exact error and installed version. A research_output_invalid or research_tool_loop_incomplete error is a validation failure, not evidence that your provider key is wrong.

Older releases have reported research routing and finalization defects. Preserve the failed task details and follow the upgrade guide when installing a release containing the fixes.

07 / DAILY WORK

Clients, assets and revisions

Keep each client’s work and context together.

1. Create or select a client before a new assignment. Add relevant brand guidance and factual background rather than repeating them loosely in every brief.
2. Upload reference files in Assets or attach them to the assignment. Specify which are source material, examples or requirements.
3. Use the relevant employee workspace to inspect and edit the result. A rendered preview and an editable source are different deliverables; open the one you need.
4. For revisions, describe what to change and what to preserve. Stop active local jobs before changing worker code, because the development watcher restarts on save.

Local file references require the owner’s local worker. A cloud worker cannot read files on your laptop.

08 / WORKFLOWS

Build a repeatable workflow

Workflows connect employee steps, data and approval points. Templates depend on your purchased employee roster.

1. Open Workflows and choose an included template or start with a blank workflow.
2. Check every step’s employee, input, dependencies, provider requirements and expected output. Start with a small chain such as Research → Copywriter.
3. Run a single test with a concrete brief. Inspect each upstream deliverable before judging a downstream failure.
4. Use the approval controls for proposed external actions. Verify destination, content and account before approving.
5. After the test works, reuse the workflow with new inputs. Monitor budgets and failures rather than assuming a successful first run guarantees every future run.

A saved draft or completed employee step does not prove that an external message was sent or an asset was published.

09 / CONVERSATIONS

Set up conversations carefully

Conversation features have their own agents, sources, knowledge and testing surfaces.

1. Open Conversations → Agents and configure the intended role, qualification questions and escalation behavior.
2. Connect a supported source in Sources using your own accounts. Supply approved facts and knowledge for that client.
3. Use Test lab to rehearse common questions, missing information and handoff cases before using the agent with real contacts.
4. Review Inbox, Knowledge gaps and Insights as conversations arrive. Correct knowledge gaps before widening the use case.

Transport accounts and integration permissions are separate from AI provider access. Follow the integration-specific documentation included in docs/.

10 / TROUBLESHOOTING

Troubleshooting

Start with the visible error, installed version and whether the job is queued, running or failed.

1. Sign-in is not configured: on a fresh copy run pnpm run setup:local. If .env.local already exists, the setup command preserves it: review its local-auth and worker settings in SETUP.md instead of deleting it. Blank optional settings now use safe defaults.
2. Port occupied or wrong app address: remove an unneeded explicit PORT / CONTROL_PLANE_URL setting to let dev:stack choose an available local port. For a hosted app, run the separately configured worker:start instead of starting a second local app.
3. pnpm not found / spawn pnpm ENOENT on Windows: reopen the terminal after installing pnpm and run pnpm --version. If it works there but fails inside the app, use a release with the Windows launcher fixes; do not reset your data.
4. Codex stays pending: confirm the worker is alive, the login instructions appeared and the local owner identity matches. Older releases can queue login jobs without owner attribution; that requires a code update.
5. route_unavailable with Brave already connected: verify the web route, ownership and connection status. Older releases incorrectly rejected non-OpenRouter web routes.
6. Worker stops while the UI still loads: inspect the worker terminal and last heartbeat, restart dev:stack, then retry only the failed assignment. The web app can remain usable without a worker.
7. No progress: inspect the most recent tool and provider error before retrying. Avoid repeatedly dispatching duplicates while a job still runs.
8. Render problems: run pnpm run doctor and check Chrome/FFmpeg capability rows. The first Chrome download needs network access and can take longer than later renders.
9. For support, include version, OS, Node/pnpm versions, employee, provider route, task/job ID, steps, expected result and exact redacted error. Exclude .env files, API keys, tokens and private customer content.

The bug report for 1.8.0 describes product defects as well as setup symptoms. Reinstalling dependencies alone does not fix a release’s code defects.

11 / UPGRADE

Upgrade without losing your work

Keep the existing installation intact while reviewing a new release.

1. Back up the current source, .env.local, local .wrangler data, deployed database/media and persistent worker state as applicable. Keep an untouched copy of the release you originally installed.
2. Extract the new release into a separate folder. Read UPGRADE.md and its release notes, then compare your current code against the old and new release.
3. Preserve configuration, credentials, data, branding and deliberate customizations. Review conflicts file by file rather than copying the ZIP over the current installation.
4. Stop active jobs before replacing worker code. Install from the updated lockfile, run doctor, typecheck and tests, then start the app and verify one small assignment.
5. If a hosted control plane and workers are separate, update the compatible components together. Keep backups and the old release available for recovery.

Do not rerun fresh-install setup or rotate encryption keys as an upgrade shortcut.

12 / HOSTING

Put your installation online

Local setup is enough to learn the tool. Hosting adds authentication, persistence and a worker that stays online.

1. Follow SETUP.md and docs/worker-deployment.md from your exact release. Configure your own Cloudflare D1 database and R2 bucket; keep real resource IDs private.
2. Configure Clerk authentication and production secrets, including a private CREDENTIAL_KEK and a matching WORKER_SHARED_SECRET on the app and worker. Disable local-auth mode.
3. Set PUBLIC_APP_URL to the public HTTPS app URL and CONTROL_PLANE_URL on the worker to that same deployment.
4. Run a worker with persistent WORKER_STATE_DIR and a stable WORKER_ID. Use WORKER_MODE=local for a person’s local CLI account; use appropriate API credentials for a shared worker.
5. Check deployment readiness, sign-in, worker heartbeat and a saved deliverable before inviting users.

The web deployment does not automatically deploy the Node worker. Back up both the app data and private worker state.

13 / AGENT SETUP

Install with a coding agent

Open the extracted source folder in your coding tool. This prompt asks the agent to help you reach a real first result, not stop at a running homepage.

Your agent should explain a failed check rather than silently changing product code to bypass it.

14 / REPEAT RESULTS

Build on your first result

Keep your business details, repeat useful assignments, and build on saved results without starting from scratch.

1. In HQ, expand Your business details and save your services, audience, tone, colors and optional logo or shared brand kit. The assignment checkbox lets you decide when to use them.
2. Describe your outcome in HQ. If the route is unclear, choose Written draft, Graphic, Short video or Research, then review the request before starting.
3. In a completed assignment, use Make a graphic, Make a short video or Write an email. Review the next brief and budget; the specialist receives the saved upstream result.
4. Save a successful single-specialist assignment as a recipe. Do this again fills a new brief for review. Attach fresh source files when needed. Coordinated campaigns use workflow templates.
5. If work fails, read the recovery card for the next step: reconnect the provider or worker, revise the brief, or retry after fixing the cause. Saved outputs remain available.
6. In document and creative editors, compare saved versions before restoring an earlier one. Restoring creates another revision, preserving history.

Creative comparisons are static previews. Check playback and exports in the editor after restoring.

Keep a guide with your code.

Download the full handbook (Markdown). New source packages can include the same guide under docs/USER_GUIDE.md, plus START_HERE.md, SETUP.md and UPGRADE.md.

Follow the setup and upgrade instructions included with your exact release. This handbook also explains known symptoms from older releases; it does not change your installed code.

Open your download library