Skip to main content
Docs Navigation

Quickstart

Get ForgeOS running in under 3 minutes. By the end of this guide, your AI agent will be calling governance tools before every action.

1. Create an account

The fastest way to get started is through the ForgeOS dashboard:

Sign up at forgeos.synctek.io/register — no credit card required. 14-day free trial, full Pro-tier access.

After registering, you will be taken straight to your dashboard where you can create a project and generate an API key.

Alternative: register via curl

If you prefer to stay in the terminal:

Terminal window
curl -X POST https://forgeos-api.synctek.io/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "password": "your-secure-password"}'

You will receive a user_id in the response. Log in to get a session:

Terminal window
curl -X POST https://forgeos-api.synctek.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "password": "your-secure-password"}' \
  -c cookies.txt

This sets a forge_session cookie. Use -b cookies.txt on subsequent requests.

2. Create a project

From the dashboard, click New Project, give it a name, and select your platform. The project ID (e.g., proj_a1b2c3d4) appears in the project settings — you will need it when configuring the MCP server.

Alternative: create a project via curl

Terminal window
curl -X POST https://forgeos-api.synctek.io/api/projects \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "name": "my-app",
    "description": "My application under ForgeOS governance",
    "platform": "web"
  }'

3. Generate an API key

From the dashboard, go to Settings → API Keys and generate a new key. Your key will have the prefix fos_ and is shown only once — store it securely. This key is required for the MCP server and CLI.

4. Install the package

ForgeOS ships as a single npm package — @synctek/forgeos — which includes:

  • The MCP server: connects your editor’s AI agent directly to 21 governance tools
  • The forge CLI: 18 command groups, 49 subcommands for terminal-first workflows
  • SharedMind: institutional memory that persists patterns and lessons across sessions, backed by the ForgeOS cloud API
  • Trust ledger: hash-chained audit trail for local governance decisions

Install globally:

Terminal window
npm install -g @synctek/forgeos

Or use npx for zero-install (MCP server):

Terminal window
npx -y @synctek/forgeos@latest

4a. CLI quickstart (optional)

If you prefer working from the terminal, the forge CLI is available after global install:

Terminal window
# Initialize a project
forge project create --name my-app


# Query SharedMind for institutional knowledge
forge mind query --context "authentication patterns"


# Check gate status for a changeset
forge gate status --changeset cs_abc123

Note: forge scorecard and forge quickstart are MCP tools, not CLI commands. Run them from your AI agent via the MCP server.

The CLI and MCP server share the same ForgeOS instance — you can use both together.

5. Configure your editor

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project, or global settings):

{
  "mcpServers": {
    "forgeos": {
      "command": "npx",
      "args": ["-y", "@synctek/forgeos@latest"],
      "env": {
        "FORGEOS_ENGINE_URL": "https://forgeos-api.synctek.io",
        "FORGEOS_API_KEY": "fos_your_api_key_here"
      }
    }
  }
}

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "forgeos": {
      "command": "npx",
      "args": ["-y", "@synctek/forgeos@latest"],
      "env": {
        "FORGEOS_ENGINE_URL": "https://forgeos-api.synctek.io",
        "FORGEOS_API_KEY": "fos_your_api_key_here"
      }
    }
  }
}

VS Code (Copilot)

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "forgeos": {
        "command": "npx",
        "args": ["-y", "@synctek/forgeos@latest"],
        "env": {
          "FORGEOS_ENGINE_URL": "https://forgeos-api.synctek.io",
          "FORGEOS_API_KEY": "fos_your_api_key_here"
        }
      }
    }
  }
}

Other MCP clients

Any MCP-compatible client works. Set these environment variables:

  • FORGEOS_ENGINE_URL = https://forgeos-api.synctek.io
  • FORGEOS_API_KEY = your ForgeOS API key (obtained from the ForgeOS dashboard)

Then run the MCP server via stdio: npx -y @synctek/forgeos@latest

6. Run your first governance command

Open your editor and ask your AI agent:

“Initialize ForgeOS for my project.”

The agent will call forge_init with your project ID. You will see the project state, active initiatives, governance rules, and workflow runbook returned.

Then try:

“Create an initiative for adding user authentication.”

The agent calls forge_create_initiative, creating a tracked initiative with a generated ID. From here, every change goes through gates — propose a changeset, submit evidence, get reviews, and promote gates before code ships.

Next steps

  • Authentication — API key management, rate limits, and security
  • MCP Server — All 21 governance tools with parameters and examples
  • REST API — Full HTTP endpoint reference