Introduction — Phantom Developer Documentation

Overview

Phantom is a developer-focused platform designed to simplify the orchestration of event-driven systems, microservices, and edge integrations. This introductory document is intended for engineers, technical writers, and platform teams who are responsible for onboarding projects, designing integrations, and authoring robust automation flows with Phantom.

What you'll find in this guide

This article covers: a high-level architecture (why Phantom exists), a fast getting-started path, code snippets for common use-cases, best practices, and a short FAQ. Headings use <h1> through <h5> to show structure and the HTML examples are provided inline so you can copy directly into your docs or website.

Why Phantom?

Modern distributed systems require components to be responsive, resilient, and observable. Phantom's mission is to provide:

• Composability: assemble small building blocks into powerful workflows.
• Low-latency: handle events and messages with predictable latency.
• Observability: out-of-the-box tracing and insights for every step.
• Developer ergonomics: concise SDKs, first-class testing utilities, and approachable docs.

Core Concepts

1. Workers

Workers are lightweight, single-responsibility processes that run your code in response to triggers. They are the primary compute units in Phantom.

2. Triggers

Triggers are events—HTTP requests, message queue deliveries, scheduled cron-like events, webhook posts—that kick off a worker execution.

3. Connectors

Connectors are first-class integrations to external systems (databases, SaaS APIs, cloud services). Connectors can be reused across many workers.

4. Flows

Flows are declarative descriptions of orchestration: sequences, branches, retries, compensation steps.

Getting Started — Fast Path

The fastest way to get Phantom running locally is to follow these minimal steps: install the CLI, scaffold a project, run the dev server, and deploy a test worker. Below you'll find a typical example. Replace phantom with your system's package manager command if needed.

1. Install CLI

# macOS / Linux (example)
curl -fsSL https://get.phantom.dev/install | bash

# or npm based CLI
npm install -g phantom-cli
        

2. Scaffold a project

# Create a new project
phantom init my-phantom-app --template=starter

cd my-phantom-app
# Install dependencies
npm install
        

3. Start local dev server

# Start the local runtime with hot reload
phantom dev
        

4. Deploy (optional)

# Deploy to Phantom cloud (or your infra)
phantom deploy --env production
        

Example: HTTP Trigger Worker

Here is an example worker that responds to an HTTP request and forwards data to a connector.

<!-- file: workers/echo-worker.js -->
export async function handler(req) {
  const payload = await req.json();
  // Basic validation
  if(!payload || !payload.message) {
    return new Response(JSON.stringify({ error: 'Missing message' }), { status: 400 });
  }

  // Example: use a connector (pseudo API)
  await connectors.logs.write({ message: payload.message, ts: Date.now() });

  return new Response(JSON.stringify({ echo: payload.message }), {
    headers: { 'Content-Type': 'application/json' }
  });
}

How to declare the trigger

<!-- phantom.yaml -->
workers:
  - name: echo-worker
    src: workers/echo-worker.js
    triggers:
      - http:
          path: /api/echo
          method: POST

Save these files, run phantom dev, and POST JSON to http://localhost:8787/api/echo.

Advanced: Flow with Retry and Compensation

Flows let you model complex business logic. The following declarative flow demonstrates a payment attempt with retry and a compensation path on failure.

<!-- flows/payment-flow.yaml -->
flow: payment
steps:
  - id: charge
    worker: workers/charge-card.js
    retry:
      attempts: 3
      backoff: exponential
  - id: record
    worker: workers/record-transaction.js
    on_failure:
      compensate:
        worker: workers/refund.js

Why declarative flows?

Declarative flows separate the "what" from the "how." They make workflows auditable, versionable, and simpler to test.

Testing flows

Use the Phantom test harness to simulate failures and assert compensation behavior:

phantom test --flow=payment --simulate failure:charge

Developer Tools & Debugging

Phantom provides a suite of tools aimed at the developer experience: a local CLI with hot reloading, a visual flow inspector, request replay, and rich logs.

Local dev features

• Hot reloading for workers and flows.
• Request replay to reproduce bugs deterministically.
• Step-through debugger integrated with VS Code (via extension).

Observability

Each worker execution emits structured events. Use built-in dashboards or plug into your preferred APM (OpenTelemetry compatible).

Log sample

{
  "timestamp": "2025-10-22T12:34:56Z",
  "worker": "echo-worker",
  "level": "info",
  "message": "processed request",
  "meta": { "requestId": "req_abc123", "durationMs": 12 }
}

Security & Secrets

Phantom treats secrets as first-class: never commit secrets to source. Use the CLI or UI to store secrets and reference them at runtime.

Store a secret

# Secrets are environment-scoped
phantom secrets set DB_PASSWORD --env production
        

Use a secret in your worker

const dbPass = process.env.DB_PASSWORD;
// or using Phantom's secret API
const dbPass = secrets.get('DB_PASSWORD');

Best practices

1. Least privilege: grant connectors minimal permissions.
2. Rotate secrets frequently and automate rotation when possible.
3. Encrypt secrets at rest and in transit.

Performance & Cost Considerations

Phantom's billing model is usage-driven. Optimize for latency and cost by batching external calls, using efficient connectors, and caching where appropriate.

Tips for efficiency

• Batch network calls when possible.
• Use idempotent retries to avoid duplicate side effects.
• Prefer streaming for large payloads instead of buffering everything in memory.

Example: small-batch processing

// process messages in batches of 50
const chunkSize = 50;
for (let i=0;i