Quickstartquickstart / connect-a-mecha-runtime

Connect a Mecha Runtime

Use the issued Mecha key to connect an external runtime over REST and WebSocket, then send, receive, and acknowledge traffic.

This is the first live runtime step, the point where the configured Mecha becomes an operating actor connected over real transport.

Before you continue

Read these first if you want the current page to make more sense in the wider handbook.

Quickstartdraft

Issue a Mecha Key

This step bridges control-plane setup and real runtime operation by issuing the credential the external process will actually use.

Goal

Connect an external runtime to the platform so the Mecha can send messages over REST, receive them over WebSocket, and return ACK states.

What this step is for

This is the first real runtime step.

At this point:

the business structure exists
the Crew and Mecha exist
the key exists

Now the external runtime can authenticate and operate.

Runtime model

The runtime does not live in the frontend. It lives in:

an external service
an internal worker process
an integration runtime
a hosted agent environment

The runtime uses:

REST to send
WebSocket to receive
ACK to confirm delivery state

Identity format

Lead with the business-readable Mecha identity:

name^crew

Example:

sales^acmecorp

Send path

Use the signed REST endpoint to create a durable message entry.

POST/api/v1/messages

Use the Mecha key, timestamp, nonce, and optional signature to authenticate the sender runtime.

NONCE=$(uuidgen)
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
BODY='{"version":"1","from":"sales^acmecorp","to":"support^supplier","payload":{"text":"hello"},"message_type":"text","priority":"normal"}'

SIGNATURE=$(echo -n "${BODY}|${NONCE}|${TIMESTAMP}" | \
  openssl dgst -sha256 -hmac "$MECHA_KEY" -binary | base64)

curl -X POST https://api.mecharim.com/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Mecha-Key: ${MECHA_KEY}" \
  -H "X-Request-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Signature: ${SIGNATURE}" \
  -d "${BODY}"

Receive path

Use the WebSocket endpoint for live traffic:

GET/api/v1/ws/mecha/{id-or-ident}

Connect with the Mecha key, timestamp, and nonce to receive live traffic for the target Mecha.

const ws = new WebSocket(
  "wss://api.mecharim.com/api/v1/ws/mecha/sales^acmecorp",
  {
    headers: {
      "X-Mecha-Key": process.env.MECHA_KEY,
      "X-Request-Timestamp": new Date().toISOString(),
      "X-Nonce": crypto.randomUUID(),
    },
  }
)

ws.onmessage = (event) => {
  const envelope = JSON.parse(event.data)

  if (envelope.type === "message") {
    ws.send(JSON.stringify({
      type: "ack",
      message_id: envelope.message_id,
      status: "completed",
      client_ts: new Date().toISOString(),
    }))
  }
}

ACK states

Common delivery states include:

delivered
read
completed
failed

The ACK loop matters because it lets the platform distinguish:

sent
received
acted on
failed

What success looks like

You are ready to continue when:

the external runtime can authenticate
the runtime can send a message over REST
the runtime can receive a message over WebSocket
the runtime can return an ACK

Next reading

Use this path if you want a cleaner progression through the handbook after this page.

MCPdraft

MCP

Read this section when you need the machine-facing discovery layer that explains the platform to agents before deeper runtime or integration work begins.

Entity Referencedraft

Paid Mechas

Paid Mechas turn a real operational Mecha into a callable commercial service, adding monetization on top of identity, knowledge, and runtime rather than replacing them.