Skip to content

workspace.md

Latest commit

 

History

History
400 lines (278 loc) · 7.79 KB

workspace.md

File metadata and controls

400 lines (278 loc) · 7.79 KB
Raw

Workspace Quickstart

This guide walks you through initializing, configuring, and running an A.R.C. workspace.

Table of Contents

Overview

An A.R.C. workspace is a directory containing:

  • arc.yaml - Your workspace manifest (source of truth)
  • .env - Environment variables for your services
  • .arc/ - System directory for state and generated configs

The workspace follows the Operator Pattern: you declare your desired state in arc.yaml, and the CLI generates complete infrastructure configurations automatically.

Prerequisites

Before starting, ensure you have:

  1. A.R.C. CLI installed

    # Verify installation
arc --version

  2. Docker Desktop (for running the platform)

Quick Start

1. Initialize a Workspace

# Create a new workspace in the current directory
arc workspace init

# Or specify a path
arc workspace init ./my-project

This creates:

my-project/
├── arc.yaml          # Workspace manifest
├── .env              # Environment variables
├── .gitignore        # Git ignore rules
└── .arc/
    ├── state/        # Workspace state
    ├── data/         # Persistent data
    └── generated/    # Generated configs

2. Configure Features

Edit arc.yaml to enable the features you need:

version: "1.0.0"

features:
  voice: true         # Voice AI capabilities
  security: true      # Authentication & authorization
  observability: true # Metrics, logs, and traces
  chaos: false        # Chaos engineering (optional)

environment:
  LOG_LEVEL: "info"
  ENVIRONMENT: "development"

3. Generate and Run

# Generate configs and launch the platform
arc workspace run

# Or generate configs only (without launching)
arc workspace run --generate-only

# Run in detached mode (background)
arc workspace run --detached

4. Check Workspace Status

# View workspace information
arc workspace info

# View operation history
arc workspace history

Workspace Commands

arc workspace init [path]

Initialize a new workspace.

Flags:

  • -f, --force - Reinitialize existing workspace
  • --skip-gitignore - Don't create/update .gitignore

Examples:

arc workspace init                    # Current directory
arc workspace init ./my-project       # Specific path
arc workspace init --force            # Reinitialize

arc workspace run

Generate configurations and launch the platform.

Flags:

  • -d, --detached - Run in background
  • --generate-only - Generate configs without launching
  • --no-validate - Skip Docker validation

Examples:

arc workspace run                     # Interactive mode
arc workspace run -d                  # Background mode
arc workspace run --generate-only    # Configs only

arc workspace info

Display workspace state and configuration.

Flags:

  • --no-color - Disable colored output

Output includes:

  • Workspace root and manifest location
  • Enabled features
  • State information (init time, last update)
  • Recent operations

arc workspace history

Show operation history.

Flags:

  • -n, --limit N - Limit to N entries
  • -t, --type TYPE - Filter by type (init, generate, run)
  • -s, --status STATUS - Filter by status (success, failed)
  • --no-color - Disable colored output

Examples:

arc workspace history                 # Full history
arc workspace history -n 10           # Last 10 operations
arc workspace history -t generate     # Only generation ops
arc workspace history -s failed       # Only failed ops

Configuration

arc.yaml Structure

# Version of the manifest schema
version: "1.0.0"

# Feature flags to enable/disable capabilities
features:
  voice: false         # Voice AI (Daredevil, Scarlett)
  security: false      # Auth (J.A.R.V.I.S., Nick Fury)
  observability: false # Monitoring (Dr. House, Watson, Friday)
  chaos: false         # Chaos testing (Loki)

# Service-specific overrides (optional)
services:
  arc-gateway:
    config:
      port: 8080
      enable_tls: false

# Environment variables for all services
environment:
  LOG_LEVEL: "info"
  ENVIRONMENT: "development"

Environment Variables (.env)

Common variables you might configure:

# Logging
LOG_LEVEL=info

# Database
POSTGRES_USER=arc
POSTGRES_PASSWORD=your-secure-password
POSTGRES_DB=arc

# Redis
REDIS_PASSWORD=your-redis-password

# Security
SESSION_SECRET=your-session-secret
JWT_SECRET=your-jwt-secret

# Voice AI
OPENAI_API_KEY=sk-your-api-key

Example Configurations

Minimal (Gateway Only)

version: "1.0.0"

features:
  voice: false
  security: false
  observability: false
  chaos: false

Voice AI Platform

version: "1.0.0"

features:
  voice: true
  security: false
  observability: false
  chaos: false

environment:
  LOG_LEVEL: "info"
  VOICE_MODEL: "whisper-large"
  VOICE_PROVIDER: "openai"

Production-Ready (Security + Observability)

version: "1.0.0"

features:
  voice: false
  security: true
  observability: true
  chaos: false

services:
  arc-gateway:
    config:
      enable_tls: true
      enable_https_redirect: true

environment:
  LOG_LEVEL: "warn"
  ENVIRONMENT: "production"
  SESSION_TTL: "24h"
  MFA_REQUIRED: "true"

Full Development Stack

version: "1.0.0"

features:
  voice: true
  security: true
  observability: true
  chaos: true

environment:
  LOG_LEVEL: "debug"
  ENVIRONMENT: "development"
  TRACING_SAMPLE_RATE: "1.0"

Troubleshooting

"Not in an A.R.C. workspace"

You're running a workspace command outside of a workspace.

Solution:

# Initialize a new workspace
arc workspace init

# Or navigate to an existing workspace
cd /path/to/workspace

"Docker is not installed"

Docker is required to run the platform.

Solution:

  1. Install Docker Desktop from https://docs.docker.com/get-started/get-docker/
  2. Restart your terminal
  3. Verify with docker --version

"Docker is not running"

Docker is installed but the daemon isn't running.

Solution:

  1. Start Docker Desktop from your applications
  2. Wait for it to fully start (whale icon in system tray)
  3. Verify with docker ps

"Port conflict detected"

Multiple services are trying to use the same port.

Solution:

  1. Check which services conflict in the error message
  2. Update arc.yaml to use different ports: 
    services:
  arc-api:
    config:
      port: 8081  # Changed from 8080
  3. Regenerate configs with arc workspace run --generate-only

"Manifest validation failed"

Your arc.yaml has syntax or validation errors.

Solution:

  1. Check the error message for line number and field
  2. Validate YAML syntax (use a YAML validator)
  3. Ensure all required fields are present
  4. Check for typos in feature/service names

Generated files were modified

If you manually edit files in .arc/generated/, they will be overwritten on the next run.

Solution:

  • Don't edit generated files directly
  • Make all changes in arc.yaml and environment files
  • Use service config overrides in arc.yaml for customization

Next Steps

Last Updated: 2025-12-27