Activepieces Integration — Orch8 Docs

Activepieces Integration#

Run compatible Activepieces community pieces through an optional Node.js sidecar. Install the exact piece packages you need, allowlist them, and test each action contract before production use.

The Activepieces integration runs as a sidecar service (Node.js) that dynamically loads and executes Activepieces community pieces on demand. The engine dispatches steps with the ap:// prefix to this sidecar over HTTP.

Installed pieces

Use supported actions from the piece packages you explicitly install and allowlist.

Zero Compilation

Pieces are loaded dynamically at runtime. Add new connectors without rebuilding the engine.

Engine controls

Apply step retry, timeout, and circuit-breaker policies around sidecar dispatch.

Architecture

Quick Start#

1. Start the sidecar

Bash

cd engine/activepieces
npm install
npm start

# Sidecar now listening on http://127.0.0.1:50052

2. Store credentials

JSON

POST /credentials

{
  "id": "slack-bot-token",
  "kind": "api_key",
  "value": "xoxb-your-slack-token",
  "tenant_id": "tenant-1"
}

3. Use in a workflow

JSON

{
  "type": "step",
  "id": "notify-team",
  "handler": "ap://slack.send_channel_message",
  "params": {
    "auth": {
      "access_token": "credentials://slack-bot-token"
    },
    "props": {
      "channel": "#alerts",
      "text": "Deployment complete for {{context.data.service}}"
    }
  }
}

Handler Format#

Activepieces handlers use the ap:// URI scheme:

ap://<piece-name>.<action-name>

Examples:
  ap://slack.send_channel_message
  ap://google-sheets.insert_row
  ap://gmail.send_email
  ap://stripe.create_charge
  ap://github.create_issue
  ap://hubspot.create_contact
  ap://notion.create_page
  ap://discord.send_channel_message
  ap://airtable.create_record

Component	Format	Examples
piece-name	lowercase, alphanumeric + hyphens	`slack`, `google-sheets`, `hubspot`
action-name	snake_case	`send_channel_message`, `insert_row`, `create_issue`

Step Parameters

Field	Type	Description
auth	object (optional)	Authentication credentials passed verbatim to the piece. Shape is piece-specific.
props	object (optional)	Action-specific parameters. Each action defines its own schema.

Authentication#

Each piece defines its own auth shape. Use Orch8's credential system to store secrets and reference them with credentials:// URIs. The engine resolves credentials before dispatching to the sidecar.

Common Auth Patterns

API Token (Slack, Discord, etc.)

JSON

"auth": {
  "access_token": "credentials://slack-bot-token"
}

OAuth2 (Google, GitHub, etc.)

JSON

"auth": {
  "access_token": "credentials://google-oauth/access_token",
  "client_id": "credentials://google-oauth-client/client_id",
  "client_secret": "credentials://google-oauth-client/client_secret"
}

API Key (Stripe, SendGrid, etc.)

JSON

"auth": {
  "api_key": "credentials://stripe-live"
}

OAuth2 refresh: The sidecar does NOT handle token refresh. Use Orch8's built-in OAuth2 auto-refresh on your credentials (see Credentials guide), or refresh tokens in a preceding workflow step.

Sidecar Setup#

Environment Variables

Variable	Default	Description
ORCH8_AP_PORT	50052	Sidecar listen port
ORCH8_AP_HOST	127.0.0.1	Bind address (use 0.0.0.0 for Docker)
ORCH8_AP_TIMEOUT_MS	60000	Per-action execution timeout in ms
ORCH8_AP_ALLOWLIST	(none)	Comma-separated piece names. If set, only whitelisted pieces can load.
ORCH8_ACTIVEPIECES_URL	http://127.0.0.1:50052/execute	Engine-side: sidecar endpoint URL

Deployment

The engine image is published independently. Build the Node sidecar from the activepieces/ workspace so the installed piece packages and allowlist are explicit; 0.7.0 does not publish a prebuilt sidecar container.

Bash

# Engine — pin the released image
docker run --rm -p 8080:8080   -e ORCH8_ACTIVEPIECES_URL=http://host.docker.internal:50052/execute   ghcr.io/orch8-io/engine:0.7.0 --insecure

# Sidecar — from the engine repository
cd activepieces
npm install
npm install @activepieces/piece-slack @activepieces/piece-gmail
npm run build
ORCH8_AP_HOST=0.0.0.0 ORCH8_AP_PORT=50052 ORCH8_AP_ALLOWLIST=slack,gmail node dist/index.js

Health Check

GET http://127.0.0.1:50052/health

Response:
{ "ok": true, "service": "orch8-activepieces-worker" }

Error Handling#

The sidecar classifies errors as retryable or permanent. The engine respects this classification for retry decisions.

Condition	Classification	Behavior
HTTP 5xx from sidecar	Retryable	Subject to step retry policy
HTTP 4xx from sidecar	Permanent	No retry, step fails
Network error (ECONNRESET, ETIMEDOUT)	Retryable	Sidecar unreachable, retry later
TypeError / SyntaxError in piece code	Permanent	Piece bug, won't succeed on retry
Action timeout exceeded	Retryable	Slow external service
Unknown error type	Retryable	Fail-open: unknown errors get retried

Timeouts

Engine-side: 5s connect timeout, 75s total request timeout

Sidecar-side: Per-action timeout (default 60s via ORCH8_AP_TIMEOUT_MS)

Max payload: 4 MiB request body limit

Examples#

Send Slack Message

JSON

{
  "type": "step",
  "id": "slack-alert",
  "handler": "ap://slack.send_channel_message",
  "params": {
    "auth": { "access_token": "credentials://slack-bot" },
    "props": {
      "channel": "#incidents",
      "text": "Alert: {{context.data.alert_message}}"
    }
  },
  "retry": { "max_attempts": 3, "initial_backoff": 2000 }
}

Insert Google Sheet Row

JSON

{
  "type": "step",
  "id": "log-to-sheet",
  "handler": "ap://google-sheets.insert_row",
  "params": {
    "auth": {
      "access_token": "credentials://google-oauth/access_token",
      "client_id": "credentials://google-client/client_id",
      "client_secret": "credentials://google-client/client_secret"
    },
    "props": {
      "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
      "sheet_name": "Leads",
      "values": ["{{context.data.name}}", "{{context.data.email}}", "{{context.data.source}}"]
    }
  }
}

Create GitHub Issue

JSON

{
  "type": "step",
  "id": "create-bug-report",
  "handler": "ap://github.create_issue",
  "params": {
    "auth": { "access_token": "credentials://github-pat" },
    "props": {
      "owner": "myorg",
      "repo": "backend",
      "title": "Bug: {{context.data.error_type}}",
      "body": "Detected at {{context.data.timestamp}}\n\n{{context.data.stack_trace}}",
      "labels": ["bug", "auto-created"]
    }
  }
}

Send Email via Gmail

JSON

{
  "type": "step",
  "id": "send-welcome",
  "handler": "ap://gmail.send_email",
  "params": {
    "auth": {
      "access_token": "credentials://gmail-oauth/access_token",
      "client_id": "credentials://google-client/client_id",
      "client_secret": "credentials://google-client/client_secret"
    },
    "props": {
      "to": ["{{context.data.user_email}}"],
      "subject": "Welcome to {{context.data.company_name}}",
      "body": "Hi {{context.data.user_name}}, thanks for signing up!"
    }
  }
}

Multi-Step: Enrich + Notify

JSON

[
  {
    "type": "step",
    "id": "enrich-lead",
    "handler": "ap://hubspot.get_contact",
    "params": {
      "auth": { "api_key": "credentials://hubspot-key" },
      "props": { "email": "{{context.data.email}}" }
    }
  },
  {
    "type": "step",
    "id": "notify-sales",
    "handler": "ap://slack.send_channel_message",
    "params": {
      "auth": { "access_token": "credentials://slack-bot" },
      "props": {
        "channel": "#sales",
        "text": "New lead: {{steps.enrich-lead.output.name}} ({{steps.enrich-lead.output.company}})"
      }
    }
  }
]

Limitations#

Actions only, no triggers

Activepieces polling/webhook triggers are not supported. Use Orch8's native trigger system for event-driven workflows.

No persistent store

The sidecar's action context store is in-memory only. Data does not persist between invocations. Use Orch8's context.data for state.

OAuth refresh is caller's responsibility

The sidecar does not refresh OAuth tokens. Use Orch8's built-in credential auto-refresh or a preceding workflow step.

File handling limited to data URLs

Files produced by pieces are returned as base64 data URLs, not persisted to storage. Large files should be handled via http_request to cloud storage.

No connection service

Activepieces' connection management is not available. Pass auth directly via params.auth using Orch8's credential system.

Available Pieces

Any published Activepieces community piece works out of the box. The sidecar dynamically installs @activepieces/piece-<name> on first use. Browse available pieces at https://www.activepieces.com/pieces.

Previous← Streaming & Approvals NextSQLite & Test Mode →