> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superwire.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a small workflow and execute it through the Docker executor.

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

<Steps>
  <Step title="Start local executor">
    Run Docker and keep the process alive.
  </Step>

  <Step title="Write a minimal workflow">
    Define one input, one model-backed agent, and one structured output.
  </Step>

  <Step title="Execute from Playground or API">
    Use the Playground for speed, then use `curl` for integration testing.
  </Step>
</Steps>

## 1. Start the executor

```bash theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
docker run --rm -p 13703:13703 rmilewski/superwire
```

## 2. Create `hello.wire`

```wire theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
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:

```text theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
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)

<Tabs>
  <Tab title="Linux">
    ```bash theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
    WORKFLOW_SOURCE_BASE64=$(base64 -w0 hello.wire)
    ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
    WORKFLOW_SOURCE_BASE64=$(base64 < hello.wire | tr -d '\n')
    ```
  </Tab>
</Tabs>

## 5. Execute it

```bash theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
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:

```json theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
{
  "message": "Hello Rafael — welcome to Superwire."
}
```

## 6. Use streaming when needed

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

```bash theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
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
```

<AccordionGroup>
  <Accordion title="Common setup issues" icon="triangle-alert">
    * 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.
  </Accordion>

  <Accordion title="What to do next" icon="arrow-right">
    * Read [Core Concepts](/core-concepts/overview) to understand workflow structure.
    * Use [Executor API](/api-reference/executor-api) for request and event details.
    * Explore [Examples](/examples/basic-agent) for more complex patterns.
  </Accordion>
</AccordionGroup>