AI Sidecar

What It Is

The AI sidecar is the Node-based companion runtime for Jetstack's embedded agent chat. It handles chat persistence, provider access, attachments, internal secrets, and provider-specific MCP connectivity concerns.

Why It Matters

The AI sidecar is the operational backbone behind the tenant AI experience. Without it, the AI agent configuration layer has nowhere to run.

Main Responsibilities

  • serve embedded chat functionality
  • manage provider requests
  • store chat state
  • manage attachment handling
  • bridge or coordinate MCP access when required by provider behavior

Environment Expectations

Typical environment requirements include:

  • chat token secret
  • internal secret
  • internal app base URL
  • optional template-based internal base URL for hostname-routed tenants
  • optional MCP server URL overrides
  • storage backend choice
  • provider fallback API keys

Credential Model

The intended credential model is:

  • agent-specific credentials through Jetstack secret references
  • sidecar env keys only as fallback defaults

That division is important because it keeps tenant implementation ownership separate from infrastructure fallback.

Agent User Identity And Application Users

The AI sidecar does not operate as an unbounded system superuser. Tenant agent sessions are tied to a configured Jetstack user identity for the agent.

This is a critical design feature because it means:

  • the agent operates through a defined tenant user
  • roles assigned to that user shape what the agent may access
  • resulting object changes remain attributable to that identity
  • the sidecar can issue a scoped access token for the agent context rather than bypassing tenant permissions

In practice, this means the same application-user pattern used for API and MCP integrations should also be used for AI agents.

  1. Create a dedicated non-human User for the agent.
  2. Give that user only the roles the agent genuinely needs.
  3. Place the user into a dedicated Group such as Application access or AI agents.
  4. Reference that dedicated user from the agent configuration.
  5. Keep secrets and provider credentials separate from the user identity itself.

Why this pattern is important

  • agent behavior remains accountable
  • permission design stays explicit
  • multiple agents can be separated cleanly by identity
  • it becomes possible to disable or review one agent without affecting human users

MCP relation

When the sidecar coordinates MCP-enabled agent access, the issued token can carry MCP-specific restrictions in addition to the underlying agent user identity. This gives the platform two layers of control:

  • the agent user’s normal roles and permissions
  • MCP-specific narrowing of tools, resources, prompts, or features

Persistence Model

The sidecar supports:

  • MySQL-backed persistence for production
  • file-backed fallback persistence for development

Deployment Considerations

Remote providers may need public MCP reachability. That makes sidecar deployment partly an infrastructure concern and partly an application-integration concern.

Best Practices

  • treat the sidecar as deployable infrastructure, not just a local helper
  • keep tenant-specific credentials in Jetstack secrets
  • document MCP reachability requirements for the chosen provider mix
  • use a dedicated application user for every important tenant agent or integration-facing assistant
  • place agent users into a dedicated group so they stay easy to review and govern
Previous← Ai Agents BuilderNextCloud Console →