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.
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
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
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.
- Create a dedicated non-human User for the agent.
- Give that user only the roles the agent genuinely needs.
- Place the user into a dedicated Group such as
Application access or AI agents.
- Reference that dedicated user from the agent configuration.
- Keep secrets and provider credentials separate from the user identity itself.
- 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
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
The sidecar supports:
- MySQL-backed persistence for production
- file-backed fallback persistence for development
Remote providers may need public MCP reachability. That makes sidecar deployment partly an infrastructure concern and partly an application-integration concern.
- 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