Workspace Hydration

Workspace hydration is the process of preparing a container with everything an agent needs before it starts. Repositories are cloned, credentials are installed, and agent context files are synthesized - all during the workspace setup phase, before the agent process runs.

The agent wakes up in a fully configured environment. It does not clone repos, manage credentials, or set up its own context. Hydration does that work up front.

Why Pre-Clone Instead of Agent-Clone?

When an agent clones its own repositories, several things go wrong:

• Raw GitHub tokens leak into the agent's environment (a security violation under ADR-024)
• Token injection time counts against the agent's context budget
• The agent wastes turns on setup instead of actual work
• Cloning errors disrupt the workflow mid-run

Workspace hydration solves all of these. Cloning happens during the setup phase using short-lived GitHub App installation tokens. Those tokens are cleared before the agent starts. The agent inherits cached git credentials and pre-populated repos - but never sees a raw token.

The repos Field

repos is a first-class field on both the workflow template and the execute API (ADR-058).

Workflow Template (default repos)

Set default repos when creating a workflow:

syn workflow create my-workflow \
  --repos https://github.com/acme/api-service \
  --repos https://github.com/acme/web-app

Or in a workflow YAML:

id: my-workflow-v1
name: My Workflow
repos:
  - https://github.com/acme/api-service
  - https://github.com/acme/web-app
phases:
  - id: analyze
    prompt_file: phases/analyze.md
    model: sonnet

Every execution of this workflow will pre-clone both repos unless overridden at run time.

Execute Override

Pass --repo at run time to override or extend the template's default repos:

# Override - use these repos instead of the template defaults
syn workflow run my-workflow-v1 \
  --repo https://github.com/acme/api-service \
  --repo https://github.com/acme/staging-fork

# Template has no repos - supply them per-run
syn workflow run my-workflow-v1 \
  --repo https://github.com/acme/feature-branch

The execute API accepts the same field:

curl -X POST /v1/workflows/{id}/execute \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Review the latest changes",
    "repos": [
      "https://github.com/acme/api-service",
      "https://github.com/acme/web-app"
    ]
  }'

Clone Directory Naming

Repositories are cloned under /workspace/repos/ using an owner__reponame format - the org and repo name joined by a double underscore.

The double underscore prevents namespace collisions when two orgs have repos with the same name (acme/api-service and other-org/api-service both clone without conflict).

$SYN_ALL_REPOS

Every phase prompt has access to $SYN_ALL_REPOS - a colon-separated list of all pre-cloned repo paths. This lets prompts reference repos without hardcoding paths:

$SYN_ALL_REPOS=/workspace/repos/acme__api-service:/workspace/repos/acme__web-app

Use it in a phase prompt:

You have access to the following repositories:

$SYN_ALL_REPOS

Review each repository and identify cross-cutting concerns.

Or split it in a script:

IFS=':' read -ra REPOS <<< "$SYN_ALL_REPOS"
for repo in "${REPOS[@]}"; do
  echo "Processing $repo"
done

$SYN_ALL_REPOS is empty (not unset) when no repos are configured. Scripts that iterate over it will correctly handle the zero-repo case.

AGENTS.md and CLAUDE.md Injection

When one or more repos are configured, the orchestrator synthesizes /workspace/AGENTS.md and /workspace/CLAUDE.md at container start. Each file contains $import directives that pull in the AGENTS.md and CLAUDE.md from every cloned repo that has one:

# /workspace/AGENTS.md (synthesized by Syntropic137)

@/workspace/repos/acme__api-service/AGENTS.md
@/workspace/repos/acme__web-app/AGENTS.md

The agent loads these files automatically via Claude Code's standard context injection. This means the agent inherits repo-specific conventions, architecture notes, and coding standards from every configured repository - with no manual setup.

If a cloned repo does not have an AGENTS.md or CLAUDE.md, it is skipped silently. If no repos are configured, no synthesis happens and /workspace/AGENTS.md is not created.

Workspace Directory Structure

A hydrated workspace looks like this:

/workspace/
  AGENTS.md              # Synthesized - imports each repo's AGENTS.md
  CLAUDE.md              # Synthesized - imports each repo's CLAUDE.md
  artifacts/
    input/               # Previous phase outputs (read-only)
    output/              # Current phase deliverables
  repos/
    acme__api-service/   # Cloned from github.com/acme/api-service
    acme__web-app/       # Cloned from github.com/acme/web-app
/opt/agentic/
  plugins/               # Pre-bundled plugins
  config/                # Runtime configuration
  version.json           # Image version manifest
  entrypoint.sh

GitHub App Token Lifecycle

Repo cloning uses GitHub App installation tokens, not personal access tokens. The lifecycle:

1. Setup phase - Orchestrator generates a short-lived installation token per repo's org and injects it into the workspace via the sidecar proxy
2. Clone - Each repo is cloned using the installation token; git credential helper caches the token for the repo URL
3. Token revocation - Raw tokens are cleared from the environment before the agent phase starts (ADR-024)
4. Agent phase - Agent uses cached git credentials for push/pull operations; it never handles the original token

The agent can push commits and open PRs using the cached credentials. The GitHub App's configured permissions determine what it can do.

Dashboard and Execution Detail

Configured repos are surfaced throughout the platform:

• Execution detail - The repos field appears on WorkflowExecutionDetail, visible in the dashboard and via syn execution show <id>
• Workflow detail - syn workflow show <id> displays the template's default repos
• Execution list - Executions show their configured repos for filtering and audit

Related

• Workspace Configuration - environment variables including $SYN_ALL_REPOS
• Workspace Security - secret injection lifecycle (ADR-024)
• GitHub Integration - GitHub App setup and permissions
• CLI: syn workflow - --repo and --repos flag reference