Get started with Forge

Introduction

A workspace describes everything your project needs locally — application services, databases, caches, brokers, search engines, storage and external services. Forge reads that description, starts only what you ask for, and keeps their health, logs, ports and resource usage visible.

Applications usually run best as native processes through their own toolchain; infrastructure runs best as containers. Forge supports both at once, and is not a container runtime, a Kubernetes distribution or an IDE.

Requirements

• A desktop OS: macOS, Windows or Linux.
• A container runtime (Docker Desktop, OrbStack or Colima) if your workspace uses container resources. Native-only workspaces don't need one.
• The usual toolchains for your own services — for example, a JDK, Node.js, Go or Rust.

Install

Download the installer for your platform from the download section and open it. Forge ships as a native desktop app and updates itself.

Quickstart

1. 01 Add a forge.yaml to the root of your repository.
2. 02 Open the repository in Forge — it detects the workspace file.
3. 03 Choose a profile, such as Backend.
4. 04 Press Start All. Forge starts dependencies in order and waits for readiness.
5. 05 Code — watch logs, health and metrics from the same window.

The whole loop, in one app: clone → open → start → code.

forge.yaml

The workspace file is human-readable and committed to Git, so the whole team reproduces the same environment. Here is a complete example you can adapt:

# forge.yaml — commit this with your code
workspace:
  name: my-project

resources:
  gateway:
    type: application
    runtime: process
    command: ./gradlew bootRun
    ports:
      - name: http
        port: 8080
    depends_on:
      - user-service
      - order-service
    health:
      http:
        url: http://localhost:8080/actuator/health
        expected_status: 200

  user-service:
    type: application
    runtime: process
    command: ./gradlew bootRun
    ports:
      - name: http
        port: 8081
      - name: grpc
        port: 9081
    depends_on:
      - postgres
      - redis
    env:
      SPRING_PROFILES_ACTIVE: local
    actions:
      test:
        command: ./gradlew test
      build:
        command: ./gradlew build

  postgres:
    type: database
    runtime: container
    image: postgres:17
    ports:
      - name: postgres
        port: 5432
    volumes:
      - forge-postgres-data:/var/lib/postgresql/data
    env:
      POSTGRES_USER: my_project
      POSTGRES_PASSWORD: my_project
      POSTGRES_DB: my_project
    health:
      tcp:
        host: localhost
        port: 5432

  redis:
    type: cache
    runtime: container
    image: redis:8
    ports:
      - name: redis
        port: 6379

  rabbitmq:
    type: messaging
    runtime: container
    image: rabbitmq:management
    ports:
      - name: amqp
        port: 5672
      - name: management
        port: 15672

profiles:
  minimal:
    - gateway
    - user-service
    - postgres
    - redis
  backend:
    - gateway
    - user-service
    - order-service
    - postgres
    - redis
    - rabbitmq
  full:
    - "*"

Resources

Each entry under resources is a resource with atype (its role) and a runtime (how it runs).

Profiles

Profiles are named sets of resources. Start only what a task needs instead of the whole platform — this is the biggest lever on local resource usage. Use"*" to include everything.

profiles:
  minimal: [gateway, user-service, postgres, redis]
  backend: [gateway, user-service, order-service, postgres, redis, rabbitmq]
  full: ["*"]

Health checks

A running process is not the same as a healthy service. Forge waits for readiness before starting dependents and reports clear states: starting, healthy, degraded, unhealthy, stopped and failed.

health:
  http:
    url: http://localhost:8081/actuator/health
    expected_status: 200
  # or
  tcp:
    host: localhost
    port: 6379
  # or
  command: redis-cli ping

Environments

Environments are named sets of variables (Local, Development, Test, Production, or custom) applied when services start. The active environment is chosen from the topbar; resource-level env overrides it. Sensitive values should be stored as secrets rather than in the workspace file.

Commands & actions

Define repeatable developer commands once and run them from the service view — output is streamed with a live status.

actions:
  test:
    command: ./gradlew test
  build:
    command: ./gradlew build
  clean:
    command: ./gradlew clean

Logs & metrics

The Logs screen aggregates native and container output into one stream with filters, severity levels, search and error investigation. The Resources screen shows CPU and memory per resource, so you can see exactly what your stack costs.

Ports

Forge tracks every declared port, detects conflicts before launch, and provides a workspace view plus a system-wide listener scan on the Network screen.

Troubleshooting

• Container resources won't start. Confirm a container runtime is installed and running — Forge shows its status in Settings → Runtime.
• Port already in use. The Network screen lists the owning process; stop it or change the port.
• A service reports unhealthy. Open its logs and health detail; a dependency outside the current profile may be stopped.
• Image pull denied. Some images now require authentication; check the registry and docker login.

Still stuck? Reach out to Airovo.