Getting started with AgentRaaS

Connecting your first agent (on Cloud, or on your own self-hosted instance) and where to find everything again later.

Not ready to run a server? pip install agentraas gives you a chaos tester that shows which API calls your agent would run twice, and an @exactly_once decorator that fixes them, both on your own machine with no account.

Cloud vs. self-hosted: which do I want?

	AgentRaaS Cloud	Self-hosted
Where it runs	Our servers	Your own server
Setup	Register, log in, done	Register, download, run install.sh
Limit	Free trial of 1,000 actions once, then Team ($19/month) or Enterprise ($29/month)	None: unlimited actions; Team/Enterprise features need a license key
Good for	Trying it out, no infra to manage	Your own data residency, unlimited volume

You can do both. Try it on Cloud first, and self-host later if you want your own instance. Nothing about your Cloud data moves to self-host automatically; they're separate.

Cloud: step by step

1. Register at the dashboard and verify your email (check your inbox, or, if you don't receive anything, check whether your deployment has email configured; a verification link is always available as a fallback in that case).
2. Log in.
3. Click Connect a service (under Setup). Pick the service, paste its API key (the window says what it's called and links to where you find it), and click Save and connect. You get the URL, the key and an example call, and the window tells you when your first call arrives. That's the whole setup for one service.
4. To connect an agent without a service yet, click + Connect agent instead, pick where it runs (n8n, Python, LangChain or CrewAI, TypeScript, an MCP client such as Claude Desktop or Cursor, Make or Zapier) and optionally name it. You get its key and the exact setup for that platform, ready to paste. Under More options:
   • Org ID: already filled in with your org. A different ID creates a separate org, for example one per client or environment. Letters, numbers, underscores, and hyphens only.
   • Agent ID: made from the name if you leave it empty, e.g. invoice-bot. Same character rules as Org ID.
5. Click Connect. You'll see:
   • API key: starts with ar_live_. Copy this now; it is shown exactly once and cannot be retrieved again. If you lose it, regenerate it from the list in + Connect agent (the old one stops working).
   • Webhook URL: where your agent sends requests.
   • MCP URL: for agent frameworks that speak MCP instead of plain webhooks.

That's it: your agent is connected. Every action it takes through AgentRaaS will show up on your dashboard within a few seconds.

Self-hosted: step by step

Self-hosting has two logins to keep straight: your AgentRaaS Cloud account (used only to get the download), and your self-hosted instance's own account (separate, lives on your own server).

1. On AgentRaaS Cloud: register, log in, and connect at least one agent first (see above). The self-host download only unlocks once you've actually tried the product.
2. Open your Account menu (click your email, top right) → Self-host AgentRaaS. Fill in the short form (what you'll use it for, and optionally your company/team name), then download the .zip.
3. On your own server, unzip it and run:

   ./install.sh

   This generates fresh secrets, runs the database migrations, and starts the stack.
4. Once it's running, go to http://your-server:13001/dashboard (or whatever host/port you configured). Your account is already pre-seeded with the email you used on Cloud. Click Forgot password and enter that same email to set a password for this instance (see SETUP_INSTRUCTIONS.txt in the download for the exact link).
5. Log in, then + Connect agent, exactly as in the Cloud steps above. This generates a fresh API key/webhook URL/MCP URL specific to your self-hosted instance. Cloud and self-hosted API keys are never interchangeable.

Where do I find these values again later?

• API key: nowhere. It's shown once, by design (AgentRaaS never stores it in a form we could show you again, only a hash of it). If you've lost it, connect a new agent and revoke the old one.
• Org ID / Agent ID / Webhook URL: always visible in the + Connect agent window, in your list of connected agents.
• MCP URL: the same for every agent on a given deployment, <your-instance-url>/mcp.

Making your first call

Once connected, your agent calls AgentRaaS instead of the real API directly. A plain webhook call looks like:

curl -X POST https://your-instance/v1/webhook/<org_id>/<agent_id> \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"service":"stripe","action":"payment_intent.create","payload":{"amount":500,"currency":"usd"}}'

• service: which connector to use (stripe, slack, github, resend and the rest; the Connect a service window lists them).
• action: which operation on that service. After you connect a service, the window lists its actions and the fields each one needs.
• payload: whatever that action needs, matching the real API's own fields.

AgentRaaS handles the actual call to Stripe/Twilio/whichever service, and guarantees that an identical retry within the dedup window returns the cached result instead of doing it twice.

Adding your own service credentials

Before your agent can actually call a service like Stripe or Twilio, AgentRaaS needs your API key for that service. Connect a service does this in one step (above). The Credentials panel does the same with more options, such as a separate key per end user:

1. Open Connect a service or the Credentials panel.
2. Pick the service and enter your key (or username/password, for services that use that instead). On Cloud, use a test or restricted key while you try it; for live production keys, self-host.
3. Save. It's encrypted at rest. Nobody, including AgentRaaS staff, can read it back out; it's only ever used server-side to make the call on your agent's behalf.

Optional: putting agentgateway in front (self-hosted)

If you're self-hosting and already run, or want to run, multiple AI agents/tools behind a shared edge (auth, RBAC, rate limiting, observability across more than just AgentRaaS), you can put agentgateway (a Linux Foundation project) in front of AgentRaaS's MCP endpoint instead of pointing agents at it directly. This is available on every tier; it's a deployment choice, not one of AgentRaaS's own paid features.

podman-compose --profile agentgateway up -d agentgateway

See config/agentgateway.yaml in the repo for the config and what it does. AgentRaaS needs zero code changes for this: your agents' existing x-agentraas-key header passes straight through. Most self-hosters don't need this; it's useful once you have more than one MCP/tool server you want to manage behind a single gateway, not a requirement for using AgentRaaS.

Something not on the list?

If the service you need isn't one of the built-in connectors, use Custom Actions to register any endpoint yourself, with the same dedup protection, same SSRF guarding, same audit trail. Open the Custom actions panel and follow the form; it walks you through the same service/action/payload shape as the built-in connectors.

---

Questions this didn't answer? hello@agentraas.io