Quickstart

This guide creates one .wire file, sends it to the executor, and reads the JSON result.

Start local executor

Run Docker and keep the process alive.

Write a minimal workflow

Define one input, one model-backed agent, and one structured output.

Execute from Playground or API

Use the Playground for speed, then use curl for integration testing.

1. Start the executor

docker run --rm -p 13703:13703 rmilewski/superwire

2. Create `hello.wire`

input {
    name: string
}

secrets {
    api_key: string
}

provider llm from openai {
    endpoint: "https://api.openai.com/v1"
    api_key: secrets.api_key
}

model fast from llm {
    id: "gpt-4.1-mini"
}

agent greeting {
    model: model.fast
    instruction: "Greet {{ input.name }} in one friendly sentence."

    output {
        message: string
    }
}

output {
    message: agent.greeting.message
}

Note: endpoint can be any OpenAI-compatible backend URL, as long as that backend supports /responses.

3. Use the Playground (fastest way to test)

You can test .wire files directly in the Playground with a visual interface, without manually base64-encoding workflow source. Open:

http://localhost:13703/playground

In the Playground, you can:

Paste or edit your .wire source.
Fill input and secrets as JSON.
Run the workflow and inspect output and events.

For quick iteration, this is the simplest way to validate and execute workflows.

4. Encode the workflow (CLI/API path)

Linux
macOS

WORKFLOW_SOURCE_BASE64=$(base64 -w0 hello.wire)

WORKFLOW_SOURCE_BASE64=$(base64 < hello.wire | tr -d '\n')

5. Execute it

curl -s http://localhost:13703/execute \
  -H 'Content-Type: application/json' \
  -d @- <<JSON
{
  "input": {
    "name": "Rafael"
  },
  "secrets": {
    "api_key": "sk-..."
  },
  "workflow_source_base64": "$WORKFLOW_SOURCE_BASE64"
}
JSON

Expected response shape:

{
  "message": "Hello Rafael — welcome to Superwire."
}

6. Use streaming when needed

/execute returns Server-Sent Events when you request text/event-stream:

curl -N http://localhost:13703/execute \
  -H 'Accept: text/event-stream' \
  -H 'Content-Type: application/json' \
  -d @- <<JSON
{
  "input": {
    "name": "Rafael"
  },
  "secrets": {
    "api_key": "sk-..."
  },
  "workflow_source_base64": "$WORKFLOW_SOURCE_BASE64"
}
JSON

Common setup issues

Ensure Docker is running and port 13703 is not already in use.
If your response is empty, verify workflow_source_base64 is populated.
If provider calls fail, confirm secrets.api_key contains a valid key.

What to do next

Read Core Concepts to understand workflow structure.
Use Executor API for request and event details.
Explore Examples for more complex patterns.

Get Started

Core Concepts

DSL Reference

MCP & Tools

Guides

Runtime

Integrations

1. Start the executor

2. Create `hello.wire`

3. Use the Playground (fastest way to test)

4. Encode the workflow (CLI/API path)

5. Execute it

6. Use streaming when needed

​1. Start the executor

​2. Create hello.wire

​3. Use the Playground (fastest way to test)

​4. Encode the workflow (CLI/API path)

​5. Execute it

​6. Use streaming when needed

1. Start the executor

2. Create `hello.wire`

3. Use the Playground (fastest way to test)

4. Encode the workflow (CLI/API path)

5. Execute it

6. Use streaming when needed