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

# Installation

> Learn what TeamCopilot is and how to install and set it up for your team.

TeamCopilot is a shared AI agent for teams. Instead of every person maintaining their own local agent setup, your team configures one shared environment that everyone can use through the same agent and web UI.

It is designed for teams that want:

* One shared agent setup instead of separate personal setups
* Shared custom skills and tools that can be reused across the team
* Permission controls for sensitive skills and tools
* Approval workflows before new skills or tools become available
* A self-hosted deployment model so chats, secrets, and data stay on your infrastructure
* Access from a web UI, including when you are away from your work machine

The docs in this site cover the main operating areas:

* setup and model authentication
* skills and workflows
* approvals and permissions
* secrets
* chat sessions and diffs
* cronjobs
* run history
* usage analytics

## Installation and setup

The quickest way to get started is with the npm-based setup from the TeamCopilot repository.

### Prerequisites

* Node.js 20+
* npm
* Python 3.10+

### 1. Initialize TeamCopilot

Run the initializer in the folder you want TeamCopilot to use:

```bash theme={null}
npx teamcopilot init
```

This writes or updates a local `.env` file in the current directory. By default, `WORKSPACE_DIR` is set to the current directory as an absolute path.

If you want to provide values up front, you can pass them during initialization:

```bash theme={null}
npx teamcopilot init \
  --workspace-dir /absolute/path/to/workspace \
  --teamcopilot-port 5124 \
  --opencode-port 4096 \
  --opencode-model openai/gpt-5.4-mini
```

### 2. Start the server

```bash theme={null}
npx teamcopilot start
```

After the server starts, open `http://localhost:5124`.

### Environment variables created by the `init` command

* `WORKSPACE_DIR`: Directory where workflows, user data and skills are stored
* `TEAMCOPILOT_HOST`: Server host, default `0.0.0.0`
* `TEAMCOPILOT_PORT`: Server port, default `5124`
* `OPENCODE_PORT`: Internal OpenCode server port, default `4096`
* `OPENCODE_MODEL`: Model used by OpenCode

If you want dashboard-generated workflow API curl examples to point at the right public host, also set `EXTERNAL_HOST` to the externally reachable base URL for the TeamCopilot instance.

## What to read next

* [Add users](/docs/adding-users)
* [Set up model access](/docs/setting-up-model)
* [Custom instructions](/docs/adding-custom-instructions)
* [Workflows and skills concepts](/docs/workflows-and-skills/concepts)
* [Chat and sessions](/docs/workflows-and-skills/chat-and-sessions)
* [Secrets](/docs/workflows-and-skills/secret-management)