Skip to main content
Version: 26.1

Co-Scientist

caution

Co-Scientist requires Seqera Platform Enterprise 25.3.6 or later. This guide covers the Enterprise 26.1 deployment path for the agent backend, MCP server, web interface, and Seqera CLI. It is currently only available on AWS.

Deploy the agent backend, Seqera MCP server, and web interface alongside Platform to provide Co-Scientist assistance for workflows, data, projects, and Platform resources in the Seqera CLI and browser. The MCP, agent backend, and portal web Helm charts provide the option to define Kubernetes ingresses. Other methods to expose the services can be used, e.g. via the extraDeploy resource.

Prerequisites​

Before you begin, make sure you have:

  • Seqera Platform Enterprise 25.3.6 or later deployed with the Seqera Platform Helm chart.
  • Helm v3 and kubectl installed locally.
  • DNS names and TLS certificates for the Platform, agent backend, MCP server, and portal web interface hosts. By default, the Helm charts derive mcp.<platformExternalDomain>, ai-api.<platformExternalDomain>, and ai.<platformExternalDomain>. Override global.mcpDomain, global.agentBackendDomain, and global.portalWebDomain if you use different hostnames.
  • Access to pull the images required by the Helm charts from the configured container registry, or mirrored copies in your internal registry. See Seqera container images and Mirroring container images.
  • A MySQL 8.4 LTS-compatible database for the agent backend. You can use the same MySQL instance as Platform with a separate database and user, or a separate instance.
  • A Redis 7.2-compatible or Valkey 7.2-compatible instance for agent backend task coordination.
  • A stable Fernet token encryption key for the agent backend if you use Kustomize. Helm-only installs can let the chart generate this key, but explicitly setting it avoids accidental regeneration.
  • Access to a supported Claude inference provider. AWS Bedrock is recommended for Enterprise deployments; direct Anthropic API access is also supported.
  • If you use AWS Bedrock, access to the required Claude model or inference profile and the Amazon Titan embedding model. See AWS documentation to add or remove access to Amazon Bedrock foundation models.
  • If you use direct Anthropic API access, an Anthropic API key stored in a Kubernetes Secret.

Generate a Fernet token encryption key when you set the key manually:

# using uv Python package manager (installed if not available)
uv --version >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
uv run --with cryptography python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# using Python directly, cryptography dependency module must be installed in environment
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Store database passwords, Redis or Valkey passwords, OIDC token values, image pull credentials, and encryption keys in Kubernetes Secrets. Reference those Secrets from Helm values instead of committing plaintext values.

Inference providers​

Co-Scientist supports two Claude inference providers. AWS Bedrock is recommended for Enterprise deployments, especially when inference must run in your AWS account or your organization wants to avoid direct egress to Anthropic. Direct Anthropic API access remains supported when your organization has approved that integration.

Inference providerDescription
AWS BedrockRecommended. Runs Claude inference in your AWS account through Bedrock.
Anthropic APIUses Anthropic-hosted Claude models through an Anthropic API key.

Documentation semantic search is configured separately from chat inference. Use Amazon Titan embeddings through Bedrock when you enable improved documentation search.

Components​

ComponentDescription
Agent backendFastAPI and LangGraph service that orchestrates Co-Scientist sessions, validates Platform tokens, calls the configured inference provider, connects to MCP, and streams Server-Sent Events (SSE) to clients.
Seqera MCP serverModel Context Protocol server that exposes Platform-aware tools for workflows, datasets, compute environments, Wave, Hub, and nf-core.
Portal web interfaceBrowser interface for Co-Scientist chat, projects, thread history, report viewing, and related Platform workflows.
MySQLAgent backend database for sessions, threads, token usage records, and conversation history.
Redis or ValkeyAgent backend queue and coordination store.

Deployment topology​

The recommended Enterprise topology is using the platform Seqera Helm chart with the mcp, agent-backend, and portal-web subcharts enabled. The Platform Helm chart automatically wires the MCP OIDC client registration token from the Platform backend secret, reducing the number of manual steps required.

Use separate Helm releases when you cannot convert your existing Platform installation to using the Helm chart or your environment requires separate lifecycle ownership. If you deploy the charts separately, you must manually configure:

  • global.platformServiceAddress and global.platformServicePort on each AI chart so they can reach the Platform backend service using the cluster-internal endpoint.
  • oidcToken.existingSecretName and oidcToken.existingSecretKey with the same OIDC client registration token configured for the Platform backend.
  • Matching external DNS and TLS for global.mcpDomain, global.agentBackendDomain, and global.portalWebDomain.

Configure Helm values​

Enable the three Co-Scientist subcharts in your Platform values file. This example uses the Platform parent chart, so the same Helm release also deploys or upgrades Platform. Include the required Platform values from your existing installation in addition to these Co-Scientist values.

global:
  platformExternalDomain: platform.example.com
  mcpDomain: mcp.platform.example.com
  agentBackendDomain: ai-api.platform.example.com
  portalWebDomain: ai.platform.example.com

mcp:
  enabled: true

agent-backend:
  enabled: true

portal-web:
  enabled: true

For a complete example, see the Co-Scientist Helm example.

Configure MCP​

When MCP runs under the Platform parent chart, leave mcp.oidcToken unset unless you need to override the default wiring. The parent chart sets it to the Platform backend secret key OIDC_CLIENT_REGISTRATION_TOKEN.

Configure the agent backend​

The agent backend needs MySQL, Redis or Valkey, inference provider access, MCP connectivity, and a stable token encryption key. In this example sensitive values (db and redis passwords, token encryption key, etc) are stored in a Kubernetes secret named seqera-ai-secrets, which needs to already exist before the chart installation, either created manually or with automated secret extraction tools (like External Secrets, not covered in this tutorial).

Declare which provider serves each capability using inference.provider, embeddings.provider, and sandbox.provider. inference.provider is required; embeddings.provider and sandbox.provider are optional. Leave them empty to disable those features. The bedrock block holds credentials and configuration shared across all Bedrock-backed services, with per-service overrides available when needed.

The following example shows a full Bedrock configuration with embeddings and AgentCore sandbox enabled. For Anthropic inference, see the note after the example.

agent-backend:
  enabled: true

  # -- Database
  database:
    host: mysql.example.com
    name: agent_backend
    username: agent_backend
    existingSecretName: seqera-ai-secrets
    existingSecretKey: AGENT_BACKEND_DB_PASSWORD

  # -- Redis or Valkey
  redis:
    host: redis.example.com
    db: 0
    existingSecretName: seqera-ai-secrets
    existingSecretKey: AGENT_BACKEND_REDIS_PASSWORD

  tokenEncryptionKeyExistingSecretName: seqera-ai-secrets

  # -- Provider routing: declare which provider serves each capability
  inference:
    provider: bedrock   # required; "bedrock" or "anthropic"

  embeddings:
    provider: bedrock   # optional; omit to disable documentation search

  sandbox:
    provider: bedrock   # optional; omit to disable AgentCore sandbox sessions

  # -- Bedrock configuration
  bedrock:
    # Default credentials applied to all Bedrock-backed services unless overridden per-service.
    # Use this when inference, embeddings, and sandbox all share the same role and region.
    default:
      assumeRoleArn: arn:aws:iam::<account-id>:role/<bedrock-access-role>
      region: <region>

    inference:
      # Anthropic inference profile ARN on Bedrock.
      anthropicModel: arn:aws:bedrock:<region>:<account-id>:inference-profile/<profile-name>

    embeddings:
      model: amazon.titan-embed-text-v2:0

    sandbox:
      # AgentCore runtime ARN — required when sandbox.provider is "bedrock".
      runtimeArn: arn:aws:bedrock-agentcore:<region>:<account-id>:runtime/<runtime-id>

Use bedrock.default.assumeRoleArn when the pod must assume a role to access Bedrock services. Leave it empty when the pod already has direct AWS credentials for the target account. Per-service overrides (bedrock.inference.assumeRoleArn, bedrock.embeddings.assumeRoleArn, bedrock.sandbox.assumeRoleArn) are available when different roles are required per capability.

To use direct Anthropic API access instead of Bedrock for inference, replace the inference and bedrock.inference blocks above with the following, and add the anthropic block. Bedrock embeddings can still be enabled alongside Anthropic inference:

  inference:
    provider: anthropic

  anthropic:
    existingSecretName: seqera-ai-secrets

  embeddings:
    provider: bedrock

  bedrock:
    default:
      assumeRoleArn: arn:aws:iam::<account-id>:role/<bedrock-access-role>
      region: <region>
    embeddings:
      model: amazon.titan-embed-text-v2:0

Use direct Anthropic API access only when your organization has approved Anthropic-hosted Claude models.

Configure the portal web interface​

The portal web chart serves the browser interface and proxies requests to the agent backend. It authenticates users through Seqera Platform.

portal-web:
  enabled: true

Install or upgrade​

Run Helm with your Platform values and Co-Scientist overrides:

helm upgrade --install seqera oci://public.cr.seqera.io/charts/platform \
  --namespace seqera \
  --values values.yaml

After installation, verify the pods are ready:

kubectl get pods -n seqera -l app.kubernetes.io/component=mcp
kubectl get pods -n seqera -l app.kubernetes.io/component=agent-backend
kubectl get pods -n seqera -l app.kubernetes.io/component=portal-web

Verify the installation​

Check the public endpoints:

curl -i https://ai-api.platform.example.com/health
curl -i https://mcp.platform.example.com/health
curl -i https://mcp.platform.example.com/service-info
curl -I https://ai.platform.example.com

The agent backend /health endpoint returns 200 OK when the service starts and required dependencies are reachable. The MCP server exposes /health for reachability and /service-info for server and protocol information. The portal web interface does not expose a matching /service-info endpoint; use the HTTP response and browser sign-in test to confirm it is reachable.

Open the portal web interface, for example https://ai.platform.example.com, and sign in with your Platform account. A successful login confirms that Platform OIDC, portal web, and the agent backend are connected. Start a chat in the interface to test the inference provider configuration; if sandboxing was configured, try asking a specific question that would trigger a sandbox execution, e.g. What's the accurate square root of 98723516236?, which should prompt the model to write a small Python script that should run in the sandbox.

Connect the Seqera CLI to Co-Scientist​

There are two options available to install Seqera CLI:

Use the install endpoint

Once Platform is installed with agent-backend and portal-web enabled, use the install endpoint to install CLI:

curl -fsSL https://<global.portalWebDomain>/install | bash
curl -fsSL https://ai.platform.example.com/install | bash

For automated environments, use a Platform access token instead of browser login.

export TOWER_ACCESS_TOKEN=<PLATFORM_ACCESS_TOKEN>
seqera ai

Set SEQERA_AUTH_CLI_CLIENT_ID only for OAuth deployments that use a non-default CLI client ID. SEQERA_ACCESS_TOKEN and TOWER_ACCESS_TOKEN are supported for token-based authentication.

Use the official npm package

Install the CLI from the official seqera npm package:

npm install -g seqera

Point the CLI at your Enterprise deployment:

export SEQERA_AUTH_DOMAIN=https://platform.example.com/api
export SEQERA_AI_BACKEND_URL=https://ai-api.platform.example.com
seqera ai

Set SEQERA_AUTH_CLI_CLIENT_ID only if your deployment uses a CLI OAuth client ID other than the default seqera_ai_cli.

For automated environments, use a Platform access token instead of browser login. Current CLI builds still require SEQERA_AUTH_DOMAIN so the CLI can target the correct Enterprise Platform authority.

export SEQERA_AUTH_DOMAIN=https://platform.example.com/api
export TOWER_ACCESS_TOKEN=<PLATFORM_ACCESS_TOKEN>
export SEQERA_AI_BACKEND_URL=https://ai-api.platform.example.com
seqera ai

Set SEQERA_AUTH_CLI_CLIENT_ID only for OAuth deployments that use a non-default CLI client ID. SEQERA_ACCESS_TOKEN and TOWER_ACCESS_TOKEN are supported for token-based authentication.

Usage and cost​

Usage and inference costs are managed by your organization through the configured inference provider, such as AWS Bedrock or Anthropic API.

Security considerations​

  • Use HTTPS for every exposed hostname.
  • Store all sensitive values in Kubernetes Secrets.
  • Keep the agent backend Fernet token encryption key stable across upgrades. Changing it prevents the backend from decrypting existing encrypted values.
  • For user-scoped operations, MCP uses the signed-in user's Platform token to call Platform APIs. Do not configure a shared administrator token for these calls.
  • Use a separate MySQL database and user for the agent backend, even if they are hosted on the same MySQL instance as Platform.
  • Enable Redis or Valkey TLS and MySQL TLS when your managed services require encrypted connections.

Learn more​

On this Page