Local development

Use this guide to run your own local Scope stack. If your organization already provides a deployment, start with Access instead. To host a shared deployment on Kubernetes, see Kubernetes self-hosting. The default local workflow uses the GitHub Copilot worker.

Prerequisites

Tool	Requirement
Git	Clone the repository; fork it first if you plan to contribute.
Node.js	Version 22, matching CI.
pnpm	Version 10.29.1, pinned in package.json.
Docker with Compose v2	Run the local stack. Use a current version with Compose Watch support.
mkcert	Create trusted HTTPS certificates for the local sign-in emulator.
GitHub CLI	Obtain a token for the Copilot quick start with gh auth login.

The Copilot worker requires an active GitHub Copilot entitlement on the account supplying its token. Authenticating with gh auth login alone does not grant Copilot access. You also need credentials with access to the models used by the Judge and other AI features. Provider usage may incur charges or consume quotas. The local backing services don’t require an Azure subscription.

The commands below use a Bash-compatible shell. Rust is only required on the host if you build or modify the gateway outside Docker.

1. Clone and install

git clone https://github.com/microsoft/scope.git
cd scope
corepack enable
pnpm install --frozen-lockfile

If you cloned a fork, run the remaining commands from that checkout instead.

2. Configure and start the stack

Authenticate with an account that has an active Copilot entitlement:

gh auth login
GITHUB_TOKEN="$(gh auth token)" pnpm docker:dev:copilot

This builds and starts the Copilot worker, Portal, API, scheduler, Judge, token manager, gateway, post-processing and reporting services, and their local dependencies. Database migrations and development agent registration run automatically. The first build downloads several images and can take some time.

The startup scripts generate the local environment file from .env.base and configure local sign-in over HTTPS. Local authentication requires your browser to trust the development certificate. The scripts run mkcert -install to add a local certificate authority to the OS/browser trust store and generate the emulator’s localhost certificate. On first use, you may be prompted to approve this trust-store change. See the local authentication instructions.

For persistent overrides, copy .env.local.example to a file named .env.local and edit it locally. Don’t put credentials in .env.base or commit them. Avoid editing the generated .env, which is regenerated by the scripts. See the environment reference for provider credentials, Judge models, and optional Azure AI Foundry configuration.

3. Open the Portal

In a second terminal, from the repository root:

pnpm open:portal

The default address is http://localhost:5100. Git worktrees get their own port assignments; pnpm open:portal resolves the correct address automatically. Local sign-in uses the seeded emulator users, such as alice@entralocal.dev, not a production Microsoft Entra tenant. See local authentication setup.

Local development is not a security sandbox

The ACP worker configuration mounts the Docker socket so agents can run containers. Use a dedicated environment for untrusted tasks, and don’t expose this development stack to the internet. Read Support and security before running sensitive workloads.

Run your first evaluation

From the Portal

1. Select or create a project to keep your evaluation data together.
2. Create a task and at least one observable evaluation criterion. For example, ask the agent to create a Node.js HTTP server and evaluate whether its source implements a GET /health route returning JSON.
3. Open the run submission page, select the running Copilot agent and an available model, and attach your task and criteria. You can save the agent configuration as a reusable profile.
4. Submit the request, follow the run’s live logs, and inspect the Judge’s results and workspace artifacts.

If no models are available, check your provider access and the model-scanner logs before submitting. A registered agent isn’t necessarily running; choose the worker enabled by your Compose command. See Submitting requests (Portal) for the full workflow.

From the CLI

Build the CLI and its shared dependency, then point it at your local API. The CLI has no default API URL, so set SCOPE_API_URL explicitly using the API_PORT value from the generated .env (3100 unless your worktree offsets it):

pnpm build:cli
export SCOPE_API_URL=http://localhost:3100
pnpm cli --help
pnpm cli project list

Select a project using the ID returned by project list:

pnpm cli project use <project-id>
pnpm cli criteria list
pnpm cli run submit --help
pnpm cli run list

Replace <project-id> with an actual ID. Submission requires a selected project, a task, and evaluation criteria. Use --project <project-id> or SCOPE_PROJECT to select a project explicitly in automation. Set SCOPE_API_URL or pass -u <url> to target another instance. See Submitting requests (CLI) for submission examples.

Coding agents

Worker	Integration	Getting started
GitHub Copilot	Agent Client Protocol (ACP)	pnpm docker:dev:copilot
Claude Code	ACP	pnpm docker:dev:claude-code

The pnpm docker:dev:all command enables both local ACP workers, not every deployment-specific integration. Each provider requires its own credentials and access to the selected models.

Next steps

Read Concepts for the evaluation building blocks, Development guide for repository layout and commands, and Contributing for how to propose changes. When you’re ready to share Scope with a team, follow Kubernetes self-hosting.