Remote Execution

Remote execution lets you trigger your RTILA X automations from outside the application — from a script, a web service, a CI/CD pipeline, or any tool that can send an HTTP request. Instead of clicking “Run” in the RTILA X interface, you send a POST request to RTILA X’s API, and your automation starts automatically.

This is incredibly powerful for integrating RTILA X into larger workflows. For example, you can trigger a scrape when a form is submitted on your website, when a file is uploaded to a server, or when a scheduled job on another system finishes.

What Remote Execution Is

Remote execution exposes a simple HTTP endpoint on your RTILA X instance. When you send a properly authenticated POST request to this endpoint, RTILA X queues and executes the specified project, just as if you had clicked “Run” in the interface.

Feature	Description
Endpoint	POST /api/remote on your RTILA X server
Authentication	Requires a project-specific API key in the request body
Response	Returns a queue ID so you can track the job
Concurrency	Prevents duplicate runs — won’t queue a second run if one is already pending or running
Works with	Projects and Trigger Chains

Enabling Remote Execution

Remote execution is configured per-project. You must enable it for each project you want to trigger remotely.

Steps

1. Go to Automation Projects in the sidebar.
2. Select the project you want to enable for remote execution.
3. Click Remote in the ribbon toolbar.
4. The Remote Execution modal opens.
5. Toggle Enable Remote Execution to On.
6. An API key is generated automatically.
7. Copy the API key — you’ll need it to authenticate your requests.

API Key

When you enable remote execution, RTILA X generates a unique API key for that project. This key is used to authenticate remote requests.

Aspect	Details
Format	A UUID string (e.g., a1b2c3d4-e5f6-7890-abcd-ef1234567890)
Storage	Stored in the project’s remote.api_key field
Scope	Unique per project — each project has its own key
Regeneration	You can generate a new key at any time. The old key stops working immediately.

To regenerate the API key:

1. Open the Remote Execution modal.
2. Click Generate New Key.
3. A new key is generated. The old key is invalidated immediately.

Triggering Remotely

The Endpoint

Send a POST request to:

POST http://YOUR_RTILA_URL:8880/api/remote

Where YOUR_RTILA_URL is:

• 127.0.0.1 for local requests
• Your public tunnel URL (e.g., https://random-xyz.trycloudflare.com) for external requests

Request Headers

Header	Value	Required
Authorization	Bearer YOUR_SESSION_TOKEN	✅ Yes
Content-Type	application/json	✅ Yes

The Authorization header requires a valid RTILA X session token. This is the PocketBase authentication token obtained when you log into RTILA X.

Request Body Format

The request body is a JSON object containing your project’s API key and optional variables:

{
  "api_key": "YOUR_PROJECT_API_KEY",
  "variables": {
    "search_term": "wireless headphones",
    "max_pages": 5
  }
}

Field	Type	Required	Description
api_key	string	✅ Yes	The project’s API key. Must match the key shown in the Remote Execution modal.
variables	object	No	Key-value pairs to pass as project variables. These override the project’s default variable values for this run.

Response Format

If the request is successful, RTILA X returns a 200 OK response with the queue ID:

{
  "id": "queue_record_id_here",
  "status": "pending"
}

Field	Type	Description
id	string	The queue record ID. You can use this to track the job’s status.
status	string	The initial status, usually "pending".

Error Responses

Status Code	Error	Cause	Solution
400	"Missing api_key"	No API key in the request body	Add the api_key field
401	"Invalid API key"	API key doesn’t match	Verify the API key in the Remote Execution modal
403	"Project not found or remote execution disabled"	Project doesn’t exist or remote is disabled	Enable remote execution for the project
409	"A job for this project is already running or pending"	A run is already in progress	Wait for the current run to finish
500	Server error	Internal error	Check the RTILA X logs

Request Examples

Triggering a Project (macOS/Linux)

curl -X POST 'http://127.0.0.1:8880/api/remote' \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "variables": {
      "search_term": "wireless headphones",
      "max_pages": 5
    }
  }'

Triggering a Project (Windows CMD)

curl.exe -X POST "http://127.0.0.1:8880/api/remote" ^
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" ^
  -H "Content-Type: application/json" ^
  -d "{\"api_key\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"variables\": {\"search_term\": \"wireless headphones\"}}"

Triggering a Project (Windows PowerShell)

$body = @{
    api_key = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    variables = @{
        search_term = "wireless headphones"
        max_pages = 5
    }
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://127.0.0.1:8880/api/remote" `
    -Method Post `
    -Headers @{
        "Authorization" = "Bearer YOUR_SESSION_TOKEN"
        "Content-Type" = "application/json"
    } `
    -Body $body

Triggering via Public Tunnel

curl -X POST 'https://random-xyz.trycloudflare.com/api/remote' \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "variables": {
      "query": "web scraping"
    }
  }'

Triggering Trigger Chains Remotely

In addition to projects, you can also trigger Trigger Chains remotely. The request format is slightly different:

{
  "api_key": "YOUR_CHAIN_API_KEY",
  "target_type": "trigger_chain",
  "variables": {
    "input_data": "value"
  }
}

Field	Type	Required	Description
api_key	string	✅ Yes	The trigger chain’s API key
target_type	string	✅ Yes	Must be "trigger_chain"
variables	object	No	Variables to pass to the chain

Public Tunnel Requirement

For remote execution to work from outside your local network, you need a public tunnel. By default, RTILA X only listens on 127.0.0.1 (localhost), which means only applications on the same computer can send requests to it.

To allow external services to trigger your automations:

1. Enable the Public Tunnel in Preferences → General.
2. RTILA X generates a public URL (e.g., https://random-xyz.trycloudflare.com).
3. Use this URL as the base for your API requests.

See Tunnels for detailed instructions.

Access Type	Base URL	Who Can Trigger
Local only	http://127.0.0.1:8880	Only applications on the same computer
Public tunnel	https://random-xyz.trycloudflare.com	Anyone with the URL and API key

Security Considerations

Consideration	Recommendation
API key secrecy	Treat the API key like a password. Never share it publicly or commit it to version control.
Session token security	The Authorization header requires a valid session token. Keep this secure.
Public tunnel awareness	The public tunnel URL is publicly accessible. Anyone who knows the URL can attempt to trigger your projects. The API key is the only protection.
Regenerate keys regularly	If you suspect a key has been compromised, regenerate it immediately. The old key stops working instantly.
Use HTTPS	When using the public tunnel, requests are sent over HTTPS (encrypted). When using localhost, traffic is unencrypted but stays on your machine.
Monitor access	Check the execution logs regularly for unexpected trigger activity.
Limit variables	Only pass variables that your project actually uses. Avoid passing sensitive data in variables if possible.
Disable when not needed	If you don’t need remote execution, disable it. This removes the attack surface entirely.

How Remote Execution Works Behind the Scenes

When RTILA X receives a valid remote execution request, here’s what happens:

1. Authentication check — The Authorization header is validated against the PocketBase session.
2. API key validation — The api_key in the request body is compared against the project’s stored remote.api_key.
3. Duplicate check — RTILA checks if there’s already a pending or running job for this project. If so, the request is rejected with a 409 error.
4. Queue creation — A new queue record is created with status "pending" and type "project_run".
5. Engine execution — The job executor picks up the pending job and launches the automation engine.
6. Execution — The project runs just as if you had clicked “Run” in the interface.
7. Completion — When the run completes, the queue record status is updated to "completed" or "failed".

Variables in Remote Requests

When you pass variables in a remote request, they override the project’s default variable values for that specific run. This is useful for parameterizing your automations.

Scenario	How to Use
Pass a search term	"variables": {"search_term": "laptop"}
Override a URL	"variables": {"target_url": "https://example.com/sale"}
Pass multiple values	"variables": {"category": "electronics", "sort": "price_asc"}
No override (use defaults)	Omit the variables field entirely

Tip: Variables passed via remote request are scoped to that single run. They don’t change the project’s saved variable values.

Integration Examples

Zapier / Make.com Integration

1. Enable remote execution for your project.
2. Enable the public tunnel.
3. In Zapier/Make.com, create an HTTP request step:
   • Method: POST
   • URL: https://YOUR_TUNNEL_URL/api/remote
   • Headers: Authorization: Bearer TOKEN, Content-Type: application/json
   • Body: {"api_key": "YOUR_KEY", "variables": {"key": "value"}}

Python Script

import requests

response = requests.post(
    "http://127.0.0.1:8880/api/remote",
    headers={
        "Authorization": "Bearer YOUR_SESSION_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "api_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "variables": {
            "search_term": "wireless headphones"
        }
    }
)

if response.status_code == 200:
    data = response.json()
    print(f"Job queued with ID: {data['id']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Cron Job (Linux/macOS)

# Run every day at 6 AM
0 6 * * * curl -s -X POST 'http://127.0.0.1:8880/api/remote' \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY"}'

Troubleshooting

Problem	Cause	Solution
“Missing api_key” error	No API key in request body	Add the api_key field to your request body
“Invalid API key” error	Wrong API key	Copy the key from the Remote Execution modal and verify it matches exactly
“Project not found” error	Project doesn’t exist or remote is disabled	Verify the project exists and remote execution is enabled
“Already running or pending” error	A run is already in progress	Wait for the current run to complete, then retry
Connection refused	RTILA X is not running or wrong URL	Verify RTILA X is running and the URL is correct
Public tunnel not working	Tunnel is not enabled	Enable the public tunnel in Preferences → General
Session token expired	Session has timed out	Log in again to get a fresh session token
Variables not being applied	Wrong variable names	Verify variable names match your project’s variable names exactly