Getting Started

The Orchestrator includes a guided setup wizard that walks you through creating your first project in five steps.

🏠 Step 1: Choose a Workspace

Select how you want to work:

• Solo: Personal workspace for individual use
• Team: Create an organization for collaborative work

If you choose Team, you’ll create an organization with a name that:

• Contains only lowercase letters, numbers, and hyphens
• Is at most 39 characters long
• Starts with a letter or number

🔗 Step 2: Select Source Control

Choose where your pipeline files are stored:

Source	Description
Orchestrator	Host pipeline files directly on the orchestrator without needing external VCS
GitHub	Fetch pipelines from a GitHub repository (supports private repos with token)
Git	Any Git server accessible via HTTP or SSH
Perforce (P4)	Agents access Perforce depots directly

The wizard validates that the repository is accessible and auto-detects any existing pipeline files (.act graphs or workflow scripts).

GitHub Private Repositories

For private GitHub repositories, provide a personal access token with repo scope. The orchestrator uses this token to fetch pipeline files and detect branches.

Git SSH

For Git repositories over SSH, ensure the orchestrator or your agents have the appropriate SSH keys configured.

📝 Step 3: Project Details

Enter a project name. When connecting to an external repository, the name is auto-filled from the repository name but can be customized.

The project is created under your personal namespace or your organization, depending on what you selected in Step 1.

⚙️ Step 4: Infrastructure Setup

Configure how the orchestrator handles secrets and artifacts.

Secrets (Vault)

Choose a vault mode for storing sensitive values:

Mode	Description
Internal	The orchestrator manages secrets internally
External (Orchestrator)	The orchestrator proxies requests to an external HashiCorp Vault instance
External (Agent)	Agents access the external Vault directly during job execution

See Secrets & Vault for detailed configuration.

Artifacts (Storage)

Choose how build artifacts are stored:

Mode	Description
Internal	Stored on the orchestrator’s local filesystem
Orchestrator Proxy	The orchestrator proxies uploads/downloads to an S3-compatible backend
Orchestrator Pre-sign	The orchestrator generates pre-signed S3 URLs for agents
Agent Direct	Agents upload directly to the S3 backend

See Storage for detailed configuration.

Note

If your organization has a security policy, some options may be locked. The wizard shows which modes are available and which are enforced by your org admin.

🤖 Step 5: Connect an Agent

To execute pipelines, you need at least one agent connected to the orchestrator. The wizard generates an agent token and shows connection commands:

Docker Bash PowerShell

docker run --rm ghcr.io/actionforge/actrun agent --token <TOKEN>

actrun agent --token <TOKEN>

actrun agent --token <TOKEN>

The agent registers with the orchestrator and begins polling for jobs. See Agents for advanced configuration and monitoring.

🚀 After Setup

Once your project is created and an agent is connected:

1. Navigate to your project dashboard
2. Trigger a pipeline run manually or via the API
3. Watch real-time logs as the agent executes your pipeline
4. View artifacts and run results when complete

The orchestrator also provides an interactive onboarding tour that highlights key UI features as you explore the platform for the first time.