Skip to main content

Quickstart

Install Rikoo, connect a model provider, build and publish an agent in the Studio, then expose it on your site or through the public API.

What you need

A machine or a Kubernetes cluster to host Rikoo, and access to a model: an API key from a hosted provider, or an OpenAI-compatible server such as Ollama or vLLM.

Set up the Studio​

1. Install Rikoo​

Installation is covered by the self-hosting guides: Docker Compose runs everything on one machine, and Kubernetes (Helm) deploys on a cluster. Come back here once the Studio answers at PUBLIC_URL, the public address of your instance (http://localhost:3000 with the Compose defaults).

2. Create the first account​

Open PUBLIC_URL and sign up. While the instance has no organization, the first account may register and create one, and it becomes its Owner. After that, people join by invitation by default (see Roles and permissions). The Community edition holds one organization, and the server refuses to create a second.

3. Use the first project​

Creating the organization also creates a first project, of which you are the owner. A project is a team workspace with its own agents, knowledge collections, MCP servers, skills, API keys and members. To add another one, use New project on the Organization screen.

4. Connect a model provider​

Open LLM APIs, click Add a provider, pick the provider, paste its API key and click Connect the provider. The key is sealed in the secret vault and the Studio never displays it again. The worker then tests the connection and discovers the models the provider serves, which become available to your agents. Connecting a provider takes the Admin or Owner role.

5. Build the agent and save a version​

Open Agents and click New agent. In Config, write the instructions and choose the main model and, optionally, fallback models from other providers. Attach a knowledge collection in Knowledge and grant tools in Tools if the agent needs them. Save a version freezes the configuration as an immutable, numbered version. Try it in Playground, which runs any saved version and keeps those runs out of production metrics.

6. Publish​

On the agent's Deploy tab, choose the environment in the selector at the top of the page (Test or Production) and enable at least one surface: the widget from Configure the widget →, or the Headless API switch. Slack answers in Production only. Then click Publish…, select the version, choose the environment under Deploy this version to and click Deploy. The version is pinned on every surface enabled in that environment, and runs already started keep the version they started with. See Environments.

Expose the agent​

The widget and the public API each reach the version published in one environment.

<!-- one script tag; the allowed origins are enforced server-side -->
<script src="$PUBLIC_URL/widget/widget.js"
        data-rikoo-token="rk_wgt_..." defer></script>

On the Deploy tab, Configure the widget → holds the design, the allowed origins, the token and this snippet for the selected environment. The rk_wgt_ token names one deployment: the agent, the surface and the environment. Details in Widget and JavaScript SDK.

# a key with the full scope; its prefix (rk_test_ or rk_live_) selects the environment
curl -X POST "$PUBLIC_URL/api/v1/agents/$AGENT_ID/conversations" \
  -H "Authorization: Bearer $RIKOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"My invoice is wrong","sync":true}'

Configure the API → on the same tab shows the endpoint, where $AGENT_ID is the agent's UUID, and creates a key limited to this agent and to the selected environment. Its value is shown once. With sync, the call waits for the run and returns the answer. Without it, the call returns the conversation and run identifiers at once, and the answer streams over SSE from /api/v1/agents/{agentId}/conversations/{conversationId}/runs/{runId}/stream. The Public API page covers the rest.

The run then appears under Monitor → Traces with its version, its model and tool calls, its tokens and its cost. If the operator has configured an OpenTelemetry collector, the trace is also exported there.

  • Core concepts: organization, project, agent, version and run, the five words the rest of the documentation assumes.
  • Self-hosting: what runs, which edition to choose and how to deploy it.