n8n workflow automation

Connect n8n to Arka’s remote agent API and verified webhook inbox — with session continuity and bidirectional triggers.

n8n is a workflow automation tool. Arka does not ship a separate n8n server. It exposes two HTTP surfaces you call from n8n HTTP Request nodes:

Endpoint	Arka service	Best for
POST /v1/agent	arka serve (port 8765)	Full agent runs, coding profile, media
POST /v1/inbox	arka webhook serve (port 8767)	Verified ingress, session continuity, silence tokens

# Inspect endpoints and copy-paste hints
arka n8n status
arka n8n example
arka n8n example --json

Prerequisites

1. Configure Arka env vars in ~/.config/arka/.env (see Configuration).
2. Start at least one HTTP listener:

# Remote agent API (recommended for general automation)
arka serve

# Verified webhook inbox (recommended for multi-turn channel sessions)
WEBHOOK_ENABLED=1 WEBHOOK_TOKEN=$REMOTE_TOKEN arka webhook serve

3. Confirm health:

curl -s http://127.0.0.1:8765/v1/health
curl -s http://127.0.0.1:8767/v1/health -H "Authorization: Bearer $REMOTE_TOKEN"

Environment variables

Variable	Default	Purpose
REMOTE_TOKEN	generated on first arka serve	Bearer token for /v1/agent and /v1/health
REMOTE_HOST	0.0.0.0	Bind address for remote server
REMOTE_PORT	8765	Remote server port
ARKA_BACKEND_URL	http://127.0.0.1:8765	Override base URL (n8n on another host, Railway, etc.)
WEBHOOK_ENABLED	0	Must be 1 to start webhook server
WEBHOOK_TOKEN	falls back to REMOTE_TOKEN	Bearer token for /v1/inbox
WEBHOOK_HOST	127.0.0.1	Webhook bind address
WEBHOOK_PORT	8767	Webhook port
MESSAGE_SESSIONS	1	When enabled, inbox uses source + chat_id for continuity

n8n → Arka: HTTP Request (agent)

Use this when you want the full Arka agent (skills, repo context, coding profile).

Node settings:

• Method: POST
• URL: http://127.0.0.1:8765/v1/agent (or your ARKA_BACKEND_URL)
• Authentication: Header Authorization: Bearer {{ $env.REMOTE_TOKEN }}
• Body (JSON):

{
  "text": "{{ $json.prompt }}",
  "remote_speak": false
}

Response: read output from the JSON body. Check ok and exit_code.

Run arka n8n example for a copy-paste node definition.

n8n → Arka: HTTP Request (inbox + sessions)

Use this for verified inbound automation with Hermes-style session continuity.

Node settings:

• Method: POST
• URL: http://127.0.0.1:8767/v1/inbox
• Authentication: Header Authorization: Bearer {{ $env.WEBHOOK_TOKEN }}
• Body (JSON):

{
  "text": "{{ $json.message }}",
  "source": "n8n",
  "chat_id": "{{ $json.session_id || 'default' }}"
}

Keep source and chat_id stable across workflow runs to preserve conversation context. The same session keys work with arka ask when MESSAGE_SESSION_CHANNEL / MESSAGE_SESSION_CHAT_ID match.

Response: output (empty when "silent": true), plus source and chat_id.

Session continuity pattern

Workflow 1 (chat_id=deploy-42): "What failed in the last deploy?"
Workflow 2 (chat_id=deploy-42): "Draft a rollback checklist."

Both POSTs use "source":"n8n" and "chat_id":"deploy-42". Arka injects prior turns before running the agent.

Arka → n8n (bidirectional)

To push events from Arka into n8n:

1. Add an n8n Webhook trigger node to your workflow and copy the Production URL.
2. POST from a shell step, routine, or agent-generated command:

curl -s "$N8N_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"event":"arka.completed","task":"nightly-health","output":"All checks passed"}'

Store N8N_WEBHOOK_URL in Arka’s .env. For scheduled pushes, use routines or an n8n Schedule trigger that polls Arka health instead.

Railway hosted option

For a cloud-hosted Arka API (coding profile), deploy with the Railway profile and point n8n at the public URL:

arka deploy --platform railway --yes
export ARKA_BACKEND_URL="https://your-arka.up.railway.app"
export REMOTE_TOKEN="your-railway-remote-token"
arka n8n status

Set REMOTE_TOKEN and provider keys in Railway Variables. See Deploy coding skills to Railway for the full hosted setup. Prefer HTTPS and keep tokens in n8n credentials, not in workflow JSON exports.

CLI reference

arka webhook serve          # start verified inbox
arka webhook status         # listener status
arka webhook status --json
arka n8n status             # endpoints + n8n hints
arka n8n example            # curl + HTTP Request JSON

Troubleshooting

Symptom	Fix
401 unauthorized	Match Authorization: Bearer token to REMOTE_TOKEN / WEBHOOK_TOKEN in Arka’s .env
Webhook won’t start	Set WEBHOOK_ENABLED=1 and WEBHOOK_TOKEN (or REMOTE_TOKEN)
No session memory between runs	Use /v1/inbox with stable source + chat_id; confirm MESSAGE_SESSIONS=1
n8n timeout	Increase HTTP Request timeout (default agent: 600s; webhook: 300s)
Works locally, not from n8n Cloud	Expose via HTTPS tunnel/reverse proxy or use Railway-hosted Arka

Start listeners before running workflows. Use arka webhook status and arka n8n status to verify URLs and tokens without invoking the agent.