Installations

Overview

An installation is how an agent picks up an outside capability. GitHub access, a Slack workspace, a knowledge-base connector, a long-term memory store: each one is an installation attached to the agent.

The installation tells you four things:

• what's attached
• whether it's connected
• what state it's in
• what to do next if it isn't usable yet

When something an agent should be able to do isn't working, the installation is the first place to look. Its status tells you what's missing.

What one installation enables

A single installation can enable several things at once. Installing a GitHub App, for example, gives the agent:

• Tools: the GitHub builtin tools (open PR, comment on issue, read file) become available as agent tools
• Knowledge: the repositories the app is installed on become available as knowledge sources the agent can index and search
• Credentials: a scoped token the agent uses for API calls, managed and refreshed by the platform

That is why installations sit upstream of both Tools and Knowledge: one attachment, multiple capabilities. When a GitHub-backed agent can't find a repo, the first place to look is whether the GitHub App installation is active, not the knowledge source directly.

---

A concrete example

Suppose Company A's support agent needs access to a site or provider-backed integration so it can help Company B diagnose a broken onboarding flow.

The operator path is:

1. inspect the available installation kinds
2. create the installation on the right agent
3. inspect its current state
4. follow the next action if setup is incomplete
5. activate it when it is ready

This is a real lifecycle, not just one create command.

---

Available installation kinds

Kind	What it connects
memory/long-term	Persistent agent memory
archastro/thread	Thread context and history
integration/github	GitHub personal OAuth (repo access, issues, PRs)
enablement/github_app	GitHub App (org-wide repo access, bot identity for PR reviews)
integration/slack	Slack user OAuth
enablement/slack_bot	Slack bot (post to channels as bot identity)
web/site	Website content for knowledge indexing

list agentinstallationkinds is the source of truth for what's available in your app. Kinds vary by app and can change over time, so always check before scripting:

archagent list agentinstallationkinds

---

Inspect available kinds

Before you attach anything, inspect the kinds the platform supports for the current app:

archagent list agentinstallationkinds

This is where you discover what categories are actually available instead of guessing from screenshots or old examples.

---

Create an installation

Create one for an agent:

archagent create agentinstallation \
 --agent <agent_id> \
 --kind web/site \
 --config '{"url":"https://status.example.com"}'

web/site here is a literal installation kind value, not a path. Different apps expose different kinds, so always start with list agentinstallationkinds before you script one.

Another installation kind may require provider-specific config instead. The exact input depends on the kind.

Installations are attached to agents explicitly. They are not ambient platform magic.

---

Inspect installation state

After creation, inspect it directly:

archagent list agentinstallations --agent <agent_id>
archagent describe agentinstallation <installation_id>

This is the command loop you use to answer:

• what state is this installation in?
• is there a next action?
• is there a provider-specific connect path?
• did setup fail?

That information is much more actionable than vague "integration isn't working" reports.

---

Activate or remove it

Some kinds auto-activate on create and start working immediately. Kinds like web/site, web/links, archastro/thread, and memory/long-term don't need an explicit activate step. They move directly to active when you create them.

Kinds that require external authorization (GitHub, Slack) stay in pending until you complete the OAuth connect flow, then activate:

archagent activate agentinstallation <installation_id>

activate is idempotent. Running it on an already-active installation is a no-op, so scripts that call it unconditionally after create stay safe.

If you no longer need an installation:

archagent delete agentinstallation <installation_id>

The explicit lifecycle keeps debugging and review straightforward. There's no hidden state to chase.

---

Org-wide integrations: enable Slack or GitHub once for everyone

Per-agent installations attach a credential to a single agent. For Slack and GitHub, an org admin can also install at the organization level: one OAuth grant, and every agent in the org inherits access without per-agent setup.

Where to enable it:

• Sign in to archagents.com as an org admin
• Open Settings → Integrations under Org settings
• Click Enable on the Slack or GitHub card and complete the OAuth flow

Behavior:

• The OAuth callback persists a system-owned integration record scoped to your org.
• Every agent in that org gets the same Slack or GitHub access through its agent tools. No per-agent agentinstallation needed for that provider. The Slack bot also exposes slack.* script bindings (see the Script Language Reference).
• Per-agent installations of the same kind continue to work in parallel. Useful when a single agent needs a narrower or different credential than the org-wide one.

When to use which:

Situation	Pick
Agent A and agent B should both post to the same Slack workspace	Org-wide
Agent A operates in workspace X, agent B in workspace Y	Per-agent
You want the fastest setup that covers every agent	Org-wide (one click for the whole org)
You're shipping an agent that needs its own narrowly-scoped credential	Per-agent

Only the Slack Bot and GitHub App providers support the org-wide path today. Slack user OAuth and GitHub personal OAuth (integration/slack, integration/github) stay per-agent.

---

How installations relate to knowledge and tools

Installations are the upstream attachment surface behind:

• knowledge connections
• provider-backed integrations
• certain tool capabilities

They matter even when a developer thinks they're "really working on knowledge" or "really working on tools." The installation's status tells you whether the underlying attachment is healthy before you debug anything higher level.

---

Best practices

Good installation workflows follow four rules:

1. inspect kinds before creating
2. attach only what the agent actually needs
3. check status and next action before blaming the model
4. activate only when the setup is clearly ready

Predictable installations make agents easier to trust as you scale up.

---

Where to go next

1. Read Knowledge for the source and ingestion layer above installations.
2. Read Tools for action surfaces the agent can operate once attachments are ready.
3. Read Webhooks when you need the lighter-weight path for an external system to push events into the platform without a full integration.
4. Read Portal for the visual operator workflow around setup and review.