Docker Installation & Deployment

🎯 Prerequisites

Resource	Minimum	Recommended
CPU	4 cores	8 cores
RAM	8 GiB	16 GiB
Disk	40 GiB	100 GiB
Architecture	x86_64 / ARM64
Software	Docker Engine 18.09+ and Docker Compose v2	A maintained Docker Engine release and Docker Compose v2

💡 Note: The recommended configuration is suitable for environments that enable the complete application, data processing, and Docker sandboxes. Model services are usually deployed separately and are not included in the resource requirements above.

Online Deployment

1. Download and Setup

bash

git clone https://github.com/ModelEngine-Group/nexent.git
cd nexent

Tip: Docker and Kubernetes share deploy/env/.env. The deployment script preserves existing configuration and adds variables introduced in deploy/env/.env.example. If .env does not exist, the script first reuses the legacy docker/.env; otherwise, it creates the file from the current template. Make sure .env.example is readable before deployment.

2. Deployment Options

Run the following command to start deployment:

bash

bash deploy.sh docker

After running the command, the script opens Bash TUI menus for deployment options. Use arrow keys or j/k to move, Space to toggle multi-select items, Enter to confirm, b/Backspace to go back, and q to quit.

Deployment Components:

infrastructure (required): Elasticsearch, PostgreSQL, Redis, MinIO
application (selected by default, optional): config, runtime, mcp, northbound, web
data-process (selected by default, optional): data processing service
terminal (optional): enables the OpenSSH terminal tool
monitoring (optional): enables observability components and then prompts for a provider

The application component also prepares the nexent-sandbox image. In v2.5.0, Docker deployments run model-generated code and Skill scripts in a system-scoped Docker sandbox by default. A sandbox is not a fixed Compose service; the Runtime service creates and reuses it according to the runtime strategy.

Port Policy:

development (default): publishes debug and internal service ports for local troubleshooting
production: publishes only production entry ports

Image Source:

general (default): uses standard public registries
mainland: uses mainland China mirrors
local-latest: uses local latest Nexent images and avoids pulling Nexent application images

You can also pass options directly:

bash

# Use saved deploy.options or built-in defaults without opening the TUI
bash deploy.sh docker --defaults

# Default component set, development port policy, standard image source
bash deploy.sh docker --components infrastructure,application,data-process --port-policy development --image-source general

# Add the terminal tool to the default component set
bash deploy.sh docker --components infrastructure,application,data-process,terminal

# Use mainland China image sources
bash deploy.sh docker --image-source mainland

+# Use local latest images
bash deploy.sh docker --image-source local-latest

HTTPS (Optional)

Nexent can terminate HTTPS at an Nginx reverse proxy installed alongside the stack. The option is disabled by default; when enabled, HTTPS uses a dedicated entry port: port 3100 for Docker deployments and NodePort 31000 for Kubernetes deployments. The plain HTTP entry (Docker 3000 / K8s 30000) stays unchanged, so both entries can be used at the same time. To change the entry ports, set NEXENT_WEB_PORT (HTTP entry) or NEXENT_HTTPS_PORT (HTTPS entry) in deploy/env/.env.

Enable it interactively (the installer asks one question: the HTTPS mode) or non-interactively:

bash

# Self-signed certificate (recommended for internal deployments)
bash deploy.sh docker --defaults --https-mode self-signed

# Your own certificate (paths may also be preset via deploy/env/.env)
bash deploy.sh docker --defaults --https-mode custom --https-cert-file /path/to/server.pem --https-key-file /path/to/server.key

self-signed: the installer generates a 99-year certificate with an unencrypted private key under <ROOT_DIR>/nginx/ssl/ and reuses it on redeployment. SAN entries are auto-detected from the host network interfaces (loopback and Docker bridges excluded); preset NEXENT_HTTPS_SAN in deploy/env/.env to override (for example NEXENT_HTTPS_SAN=10.0.0.5,example.com). Browsers show an untrusted-certificate warning; import the certificate into your trust store to silence it.
custom: point NEXENT_HTTPS_CERT_FILE and NEXENT_HTTPS_KEY_FILE at your PEM files. The installer validates the pair (PEM format, key/cert match, expiry) before deploying. Encrypted private keys are supported: provide the passphrase via NEXENT_HTTPS_KEY_PASSPHRASE or --https-key-passphrase; like other deployment credentials, it is stored in plain text in deploy/env/.env.
After enabling HTTPS, update SITE_URL in deploy/env/.env (for example SITE_URL=https://your-host:3100) so auth callbacks and generated links use the HTTPS entry point.
After changing the HTTP/HTTPS entry ports, update callback URLs such as OAUTH_CALLBACK_BASE_URL and CAS_CALLBACK_BASE_URL if they contain the old port.
Disabling HTTPS again (--https-mode disabled) removes the Nginx container; the certificate files are kept and can be reused later.

After a successful deployment, non-sensitive choices are saved to deploy/docker/deploy.options. --defaults reuses that file when it exists, otherwise it uses built-in defaults. The next interactive deployment can reuse the local config or run a full reconfiguration.

⚠️ Important Notes

1️⃣ When deploying v1.8.0 or later for the first time, Nexent creates the suadmin@nexent.com super administrator account with the default password Nexent@123, without prompting, and displays it in the terminal after successful creation. Override it before the first deployment with NEXENT_SUPER_ADMIN_PASSWORD in deploy/env/.env; non-interactive creation displays the effective password. As an exception, an offline package launched with --config prompts for and confirms the password, and that input takes precedence without being displayed.

This account is used for permission management only and cannot develop agents or create knowledge bases. Log in with this account and complete: Access tenant resources → Create tenant → Create tenant administrator, then log in with the tenant administrator account to use all features. For role permissions, see User Management.

2️⃣ For historical account upgrades, administrator failures and data recovery, use the consolidated migration runbook. Preserve the original account ID and tenant ownership; recover consistent data as described there.

Offline Deployment

When the target host cannot access public image registries, download a prebuilt offline deployment package from GitHub Actions:

Sign in to GitHub and open Build Offline Deployment Package.
Select a successful run for the required version and download the artifact matching the server architecture from Artifacts at the bottom of the run page.
Download nexent-<version>-amd64.zip for AMD64 or nexent-<version>-arm64.zip for ARM64.

GitHub Actions artifacts are retained for 30 days. If the required artifact has expired, ask a maintainer to rerun the workflow.

Copy the downloaded archive to the offline host and extract it. The downloaded artifact contains the package files directly, with no nested archive:

bash

unzip nexent-<version>-amd64.zip -d nexent
cd nexent
bash deploy.sh --load-images docker

The offline package installs all Nexent components by default. Add --config to reselect components, port policy, image source, or monitoring provider:

bash

bash deploy.sh --load-images --config docker

If the host still has a previously deployed offline package, use --reuse-from to reuse its environment configuration and deployment options:

bash

bash deploy.sh \
  --reuse-from /path/to/previous/nexent \
  --load-images \
  docker

The specified directory must be the root of an extracted previous package and contain deploy/env/.env. This option imports the old .env, preserves its values, and immediately appends variables newly introduced by the current package's .env.example. It also reuses monitoring.env and Docker deploy.options when present; the new scripts regenerate Docker-derived configuration. --reuse-from can be combined with --config, --defaults, or --push-images.

When suadmin@nexent.com is created for the first time, non-interactive deployment uses NEXENT_SUPER_ADMIN_PASSWORD, which defaults to Nexent@123, and displays the effective password after successful creation. Offline deployment with --config prompts for and confirms the password; that input is neither persisted nor displayed.

To push the packaged images to an internal registry accessible to the target environment:

bash

bash deploy.sh \
  --push-images \
  --image-registry-prefix registry.example.com/nexent \
  docker

When the prefix is omitted, the wrapper prompts for it. push-images.sh then prompts for the registry username and password before pushing.

Access Your Installation

When deployment completes successfully:

Get the administrator password: The super administrator account is suadmin@nexent.com. On its first non-interactive creation, the terminal displays the effective password; when no value was configured, the default password is Nexent@123. For an offline deployment using --config, the manually entered password is neither saved nor displayed. If it is forgotten, recreate the account by following the earlier "Recreate the suadmin account" steps.

Open http://localhost:3000 in your browser
Log in with the super administrator account
Access tenant resources → Create tenant and tenant administrator
Log in with the tenant administrator account
Refer to the User Guide to develop agents

🏗️ Service Architecture

Nexent uses a microservices architecture deployed via Docker Compose.

Application Services:

Service	Description	Default Port
nexent-config	Configuration and management API	5010
nexent-runtime	Agent runtime API	5014
nexent-mcp	MCP management and tool service	5011/5015
nexent-web	Web frontend	3000
nexent-data-process	Data processing service	5012
nexent-northbound	Northbound API service	5013

Infrastructure Services:

Service	Description
nexent-postgresql	Relational database
nexent-elasticsearch	Search and indexing engine
nexent-minio	S3-compatible object storage
redis	Cache, distributed locks, and task message broker

Optional Services:

Service	Description
nexent-openssh-server	SSH terminal for AI agents
nexent-monitoring	Optional observability stack

On-Demand Execution Environment:

Component	Description
nexent-sandbox	Isolated execution environment created by the Runtime service according to policy for running model-generated code and Skill scripts

Internal services communicate using the Docker internal network.

💾 Data Persistence

Nexent uses Docker volumes for data persistence:

Data Type	Volume Name	Default Host Path
PostgreSQL	nexent-postgresql-data	`{dataDir}/postgresql`
Elasticsearch	nexent-elasticsearch-data	`{dataDir}/elasticsearch`
Redis	nexent-redis-data	`{dataDir}/redis`
MinIO	nexent-minio-data	`{dataDir}/minio`
Agent runtime workspace	nexent-agent-workspace	Docker named volume configured by `NEXENT_SANDBOX_WORKSPACE_VOLUME`

Default dataDir is ./volumes (configurable via ROOT_DIR in deploy/env/.env).

Uninstall Docker Deployment

Use the root uninstall entrypoint from the repository root:

bash

# Stop and remove containers; keep persistent data unless you confirm deletion
bash uninstall.sh docker

# Non-interactive uninstall that keeps data
bash uninstall.sh docker --keep-volumes

# Delete Docker volumes and Nexent data under ROOT_DIR
bash uninstall.sh docker --delete-volumes true

# Full cleanup: containers plus persistent data
bash uninstall.sh docker delete-all

The Docker uninstall script reads deploy/env/.env to resolve ROOT_DIR and removes Compose resources. Data deletion removes service directories such as postgresql, elasticsearch, redis, minio, volumes, openssh-server, scripts, and skills; keep volumes when you plan to redeploy with existing data.

🔌 Port Mapping

Service	Internal Port	External Port	Description
Web Interface	3000	3000 (`NEXENT_WEB_PORT`)	Main application access
HTTPS Entry	3100	3100 (`NEXENT_HTTPS_PORT`)	Optional encrypted entry via Nginx (when HTTPS is enabled)
Backend API	5010	5010	Backend service
Runtime API	5014	5014	Agent runtime service
MCP API	5011/5015	5011/5015	MCP management and tool service
Data Processing	5012	5012	Data processing API
Northbound API	5013	5013	Northbound interface service (A2A/MCP integration)
PostgreSQL	5432	5434	Database connection
Elasticsearch	9200	9210	Search engine API
MinIO API	9000	9010	Object storage API
MinIO Console	9001	9011	Storage management UI
Redis	6379	6379	Cache service
SSH Server	22	2222	Terminal tool access

For complete port mapping details, see our Dev Container Guide.

🔧 Advanced Configuration

The v2.5.0 deployment template uses Docker sandboxes by default and reuses system-scoped containers to reduce cold-start time. The Runtime service exchanges uploaded and generated files through a dedicated workspace volume. Artifacts that must be retained are synchronized to MinIO after a run.

Common settings are defined in deploy/env/.env:

Variable	Default	Description
`NEXENT_SANDBOX_DEFAULT_LEVEL`	`docker`	Isolation level: `local`, `docker`, or `wasm`
`NEXENT_SANDBOX_DEFAULT_SCOPE`	`system`	Container lifecycle: `session` or `system`
`NEXENT_SANDBOX_DOCKER_IMAGE`	`nexent/nexent-sandbox:latest`	Docker sandbox image
`NEXENT_SANDBOX_WORKSPACE_VOLUME`	`nexent-agent-workspace`	Docker volume shared by the Runtime service and sandboxes
`NEXENT_SANDBOX_MEMORY_LIMIT_MB`	`2048`	Sandbox memory limit in MiB
`NEXENT_SANDBOX_CPU_QUOTA`	`1.0`	Sandbox CPU quota
`NEXENT_SANDBOX_TIMEOUT_S`	`30`	Per-step execution timeout in seconds
`NEXENT_SANDBOX_NETWORK`	`disabled`	Whether sandbox network access is enabled
`NEXENT_SANDBOX_SHELL_POLICY`	`disabled`	Shell invocation policy: `disabled`, `restricted`, or `boxed`
`NEXENT_SANDBOX_AUTO_SYNC_OUTPUTS`	`true`	Whether output files are automatically synchronized to MinIO
`AGENT_WORKSPACE_ROOT`	`/mnt/nexent/workdir`	Temporary file workspace for each run

Do not change the isolation level to local in production. Redeploy the Runtime service after changing resource, network, or shell policies.

Monitoring Configuration

Select the monitoring component in the deployment script UI to enable OpenTelemetry monitoring. The script synchronizes ENABLE_TELEMETRY, MONITORING_PROVIDER, MONITORING_DASHBOARD_URL, OTLP endpoints, and provider defaults in deploy/env/monitoring.env, then starts the matching observability services from deploy/docker/compose/docker-compose-monitoring.yml. Configure MONITORING_DASHBOARD_ALLOWED_ROLES to choose which roles see the frontend monitoring entry; its default is SU,SPEED.

bash

cd nexent
bash deploy.sh docker

If deploy/docker/deploy.options already exists, the script asks whether to reuse local configuration. Choose to reconfigure/overwrite local configuration, then select monitoring in the component menu and manually choose grafana, phoenix, langfuse, langsmith, zipkin, or otlp in the provider menu.

Supported providers:

Provider	Purpose	Default URL
`otlp`	OpenTelemetry Collector only, useful for forwarding to an external platform	No dashboard
`phoenix`	Local Phoenix trace analysis	`http://localhost:6006`
`langfuse`	Local Langfuse observability stack	`http://localhost:3001`
`langsmith`	Forwarding to hosted LangSmith	`https://smith.langchain.com/`
`grafana`	Local Grafana + Tempo	`http://localhost:3002/d/nexent-llm-agent/nexent-agent-trace-monitoring?orgId=1`
`zipkin`	Local Zipkin	`http://localhost:9411`

To change ports, image versions, or local Langfuse bootstrap credentials, copy and edit the monitoring environment file first:

bash

cp deploy/env/monitoring.env.example deploy/env/monitoring.env

Common variables:

Variable	Description
`MONITORING_PROVIDER`	Default monitoring provider; updated when you choose a provider in the deployment script
`MONITORING_DASHBOARD_ALLOWED_ROLES`	Comma-separated roles that can see the monitoring dashboard entry; for example `SU,ADMIN,SPEED`
`OTEL_COLLECTOR_HTTP_PORT` / `OTEL_COLLECTOR_GRPC_PORT`	Published OTLP HTTP/gRPC ports
`LANGSMITH_API_KEY` / `LANGSMITH_PROJECT`	LangSmith forwarding configuration
`LANGFUSE_INIT_USER_EMAIL` / `LANGFUSE_INIT_USER_PASSWORD`	Local Langfuse bootstrap admin
`GRAFANA_ADMIN_USER` / `GRAFANA_ADMIN_PASSWORD`	Local Grafana admin

Before choosing the langsmith provider, configure LANGSMITH_API_KEY in deploy/env/monitoring.env. If you only need to connect to an existing external Collector, adjust the OTLP target in deploy/env/monitoring.env:

bash

ENABLE_TELEMETRY=true
MONITORING_PROVIDER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http
MONITORING_DASHBOARD_URL=

Production note: Replace default passwords, secrets, and the Langfuse ENCRYPTION_KEY. Restrict dashboard and Collector access with a reverse proxy or firewall.

OAuth login uses local accounts in the application component. When enabling third-party login, set OAUTH_CALLBACK_BASE_URL to the browser-accessible Nexent Web URL.

bash

bash deploy.sh docker --components infrastructure,application

For Docker, configure OAuth in deploy/env/.env:

bash

# Web entry URL. The full callback path is generated as:
# {OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=<provider>
OAUTH_CALLBACK_BASE_URL=http://localhost:3000

# GitHub OAuth
GITHUB_OAUTH_CLIENT_ID=
GITHUB_OAUTH_CLIENT_SECRET=

# GDE OAuth
GDE_URL=
GDE_OAUTH_CLIENT_ID=
GDE_OAUTH_CLIENT_SECRET=

# Link App OAuth
LINK_APP_URL=
LINK_APP_OAUTH_CLIENT_ID=
LINK_APP_OAUTH_CLIENT_SECRET=

# WeChat OAuth
ENABLE_WECHAT_OAUTH=false
WECHAT_OAUTH_APP_ID=
WECHAT_OAUTH_APP_SECRET=

# TLS verification when contacting OAuth providers
OAUTH_SSL_VERIFY=true
OAUTH_CA_BUNDLE=

# disabled: hide OAuth login entries and disable automatic redirects
# button: show configured OAuth providers as login buttons
# force: redirect automatically when exactly one provider is configured
OAUTH_LOGIN_MODE=button

Provider enablement rules:

Provider	Required variables	Callback URL
GitHub	`GITHUB_OAUTH_CLIENT_ID`, `GITHUB_OAUTH_CLIENT_SECRET`	`{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=github`
GDE	`GDE_URL`, `GDE_OAUTH_CLIENT_ID`, `GDE_OAUTH_CLIENT_SECRET`	`{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=gde`
Link App	`LINK_APP_URL`, `LINK_APP_OAUTH_CLIENT_ID`, `LINK_APP_OAUTH_CLIENT_SECRET`	`{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=link_app`
WeChat	`ENABLE_WECHAT_OAUTH=true`, `WECHAT_OAUTH_APP_ID`, `WECHAT_OAUTH_APP_SECRET`	`{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=wechat`

For local Docker, a GitHub callback example is http://localhost:3000/api/user/oauth/callback?provider=github. In production, use a public HTTPS domain such as https://nexent.example.com/api/user/oauth/callback?provider=github and register the exact same URL in the OAuth provider console.

OAUTH_LOGIN_MODE supports disabled, button, and force, and defaults to button. In force mode, unauthenticated users are redirected when exactly one provider is enabled. OAuth is disabled when no provider is available, while multiple providers fall back to login buttons. CAS force mode takes precedence when both are configured.

CAS SSO uses local application accounts. Set CAS_CALLBACK_BASE_URL to the browser-accessible Nexent Web URL without a trailing /. CAS_SERVER_URL is the CAS Server root URL and should also not include a trailing /.

For Docker, configure CAS in deploy/env/.env:

bash

CAS_ENABLED=true
CAS_SERVER_URL=http://localhost:8080/cas
CAS_VALIDATE_PATH=/p3/serviceValidate
CAS_CALLBACK_BASE_URL=http://localhost:3000

# disabled: disable the CAS login entry and automatic redirects
# button: show CAS as an optional login button
# force: redirect unauthenticated Nexent users to CAS automatically
CAS_LOGIN_MODE=force

# Empty means use <cas:user>; set userName to read <cas:attributes><cas:userName>
CAS_USER_ATTRIBUTE=
CAS_EMAIL_ATTRIBUTE=email
CAS_ROLE_ATTRIBUTE=role
CAS_DEFAULT_ROLE=USER
CAS_TENANT_ATTRIBUTE=tenant_id
CAS_DEFAULT_TENANT_ID=tenant_id
CAS_ROLE_MAP_JSON={"cas-admin":"ADMIN","cas-user":"USER"}
CAS_SESSION_MAX_AGE_SECONDS=3600
LOCAL_SESSION_MAX_AGE_SECONDS=3600
CAS_HEARTBEAT_URL=
CAS_HEARTBEAT_INTERVAL_SECONDS=300
CAS_HEARTBEAT_COOKIE_NAME=
CAS_RENEW_BEFORE_SECONDS=300
CAS_RENEW_TIMEOUT_SECONDS=10
CAS_SYNTHETIC_EMAIL_DOMAIN=cas.local

# Empty means Nexent logout will not call the CAS Server logout endpoint.
# /logout is resolved against CAS_SERVER_URL.
CAS_LOGOUT_URL=/logout
CAS_SSL_VERIFY=true
CAS_CA_BUNDLE=

When CAS omits the role attribute selected by CAS_ROLE_ATTRIBUTE, returns it empty, or returns an unsupported role after mapping, Nexent uses CAS_DEFAULT_ROLE. Supported default roles are SU, ADMIN, DEV, and USER; invalid values fall back to USER.

When CAS omits the tenant attribute selected by CAS_TENANT_ATTRIBUTE or returns it empty, Nexent uses CAS_DEFAULT_TENANT_ID.

CAS_HEARTBEAT_URL enables a separate activity-driven heartbeat for CAS users. The first visible-page activity sends a GET immediately; later clicks, keyboard input, mouse movement, touch input, focus, or visibility changes send at most one request per CAS_HEARTBEAT_INTERVAL_SECONDS across browser tabs. If the configured Cookie is readable, Nexent sends X-Auth-Token: <cookie-name>=<cookie-value>; otherwise it sends the heartbeat without that header. The heartbeat endpoint must allow the Nexent origin, GET, OPTIONS, and X-Auth-Token through CORS. This heartbeat only keeps the authentication source active; the existing silent renewal continues to refresh the local Nexent session.

Common CAS URLs:

Purpose	URL
Nexent login entry	`{CAS_CALLBACK_BASE_URL}/api/user/cas/login?redirect=/`
CAS service callback	`{CAS_CALLBACK_BASE_URL}/api/user/cas/callback`
CAS silent renewal callback	`{CAS_CALLBACK_BASE_URL}/api/user/cas/renew_callback`
CAS single logout callback	`POST {CAS_CALLBACK_BASE_URL}/api/user/cas/logout_callback`

For Apereo CAS JSON Service Registry, create a service registration file such as Nexent-10001.json in the service registry directory configured by your CAS deployment. The id must be globally unique. This is a local Docker example:

json

{
  "@class": "org.apereo.cas.services.RegexRegisteredService",
  "serviceId": "http://localhost:3000.*",
  "name": "Nexent CAS Client",
  "id": 10001,
  "description": "Nexent CAS SSO client",
  "evaluationOrder": 1,
  "logoutType": "BACK_CHANNEL",
  "logoutUrl": "http://localhost:3000/api/user/cas/logout_callback"
}

In production, keep CAS_SSL_VERIFY=true; for self-signed certificates, prefer CAS_CA_BUNDLE and only use CAS_SSL_VERIFY=false for local testing.

CAS Integration with ModelEngine

When integrating with ModelEngine through the CAS protocol, deploy Nexent with the following configuration:

bash

CAS_ENABLED=true
CAS_SERVER_URL=https://<ModelEngine IP>:5443/SSOSvr
CAS_VALIDATE_PATH=/p3/serviceValidate
CAS_CALLBACK_BASE_URL=http://<Nexent IP>:3000
CAS_LOGIN_MODE=force
CAS_USER_ATTRIBUTE=userName
CAS_EMAIL_ATTRIBUTE=email
CAS_ROLE_ATTRIBUTE=userType
CAS_DEFAULT_ROLE=USER
CAS_TENANT_ATTRIBUTE=tenant_id
CAS_DEFAULT_TENANT_ID=tenant_id
CAS_ROLE_MAP_JSON={"1":"ADMIN","3":"DEV"}
CAS_SESSION_MAX_AGE_SECONDS=3600
LOCAL_SESSION_MAX_AGE_SECONDS=3600
CAS_HEARTBEAT_URL=https://<ModelEngine IP>:5443/<heartbeat-path>
CAS_HEARTBEAT_INTERVAL_SECONDS=300
CAS_HEARTBEAT_COOKIE_NAME=<cookie-name>
CAS_RENEW_BEFORE_SECONDS=300
CAS_RENEW_TIMEOUT_SECONDS=10
CAS_SYNTHETIC_EMAIL_DOMAIN=cas.local
CAS_LOGOUT_URL=/logout?service=http://<Nexent IP>:3000
CAS_SSL_VERIFY=false
CAS_CA_BUNDLE=

You also need to add a CAS client service registration file in the OMS container. Use the following steps as a reference:

bash

# Create the registration file, paste the JSON content into it, and save it.
vim Nexent-10000001.json
{
  "@class": "org.apereo.cas.services.CasRegisteredService",
  "serviceId": "http://<Nexent IP>:3000.*",
  "name": "Nexent CAS Client",
  "id": 1000001,
  "description": "Nexent CAS SSO client",
  "evaluationOrder": 1,
  "logoutType": "BACK_CHANNEL",
  "logoutUrl": "http://<Nexent IP>:3000/api/user/cas/logout_callback"
}

# Run the following command to copy the registration file into the container.
kubectl cp Nexent-10000001.json model-engine/$(kubectl get pods -n model-engine -l app=oms --no-headers | awk '{print $1}'):/opt/huawei/fce/apps/platform/webapps/SSOSvr/WEB-INF/classes/services/Nexent-10000001.json
kubectl exec -i -n model-engine $(kubectl get pods -n model-engine -l app=oms --no-headers | awk '{print $1}') -- chown tomcat:fusioncube /opt/huawei/fce/apps/platform/webapps/SSOSvr/WEB-INF/classes/services/Nexent-10000001.json

Northbound Interface Configuration (NORTHBOUND_EXTERNAL_URL)

If you need to use any of the following features, configure the NORTHBOUND_EXTERNAL_URL environment variable:

A2A Protocol Integration - Third-party systems calling Nexent agents via A2A protocol
MCP Tool Access - Using MCP protocol to access Nexent resources like documents

Configuration:

Set the publicly accessible URL in your deploy/env/.env file:

bash

# Format: protocol://host:port/api
# Local development (default):
NORTHBOUND_EXTERNAL_URL=http://localhost:5013/api

# Production - use your public IP or domain:
NORTHBOUND_EXTERNAL_URL=http://your-public-ip:5013/api
# or
NORTHBOUND_EXTERNAL_URL=https://api.yourdomain.com/api

Important: The URL must include the /api suffix because the Northbound service uses FastAPI's root_path="/api" configuration.

🤖 Official Agent Deployment

After Nexent is deployed, you can install official agents from the official agent resources included in the deployment package. Official agent deployment is decoupled from the Nexent platform deployment and does not run automatically when the platform starts.

Prerequisites

Before deployment, make sure that:

Nexent has been deployed with Docker or Kubernetes;
The nexent-config service is running and database initialization is complete;
The deployment package contains deploy/official-agents;
Docker deployments use Git Bash or WSL to run the script; Kubernetes deployments use a terminal with access to the target cluster.

No additional environment variables are required, and users do not need to run Git commands, docker cp, or the synchronization API manually.

Interactive Deployment

Run the following command from the Nexent repository root:

bash

bash deploy/deploy-official-agents.sh

The script scans the actual first-level directories under deploy/official-agents and presents them as the available profiles. You can enter one profile, multiple profiles such as 2,3, or all to install every profile. The script validates the directories and agent.json files. Invalid selections stop before any copy or synchronization operation.

For Docker deployments, the selected profiles are copied to /mnt/nexent/official-agents/ in the nexent-config container and then synchronized to the official agent repository.

For Kubernetes deployments, run:

bash

bash deploy/deploy-official-agents.sh --kubernetes

To specify a namespace:

bash

bash deploy/deploy-official-agents.sh \
  --kubernetes \
  --namespace custom-namespace

Using Official Agents After Deployment

After deployment, users can find the templates in the Agent Repository under the official agent list. When copying an official agent, follow the dialog to select models and choose whether to reuse or create the required knowledge bases, Skills, and MCP configurations.

The deployment stage only publishes templates. It does not create knowledge bases for every tenant. When an official agent includes a knowledge base, the target tenant must have an available embedding model when the agent is copied for the first time.

Verification

For Docker deployments, inspect the copied resources with:

bash

docker exec nexent-config find /mnt/nexent/official-agents -name agent.json -print

Then sign in to Nexent, open the Agent Repository, switch to the official agent list, and confirm that the selected profiles are available.

Delete an Official Agent

Deleting an official template requires Super Administrator privileges:

Open Resource Management;
Open the Agents page;
Click Manage Official Agents;
Select the template and confirm deletion.

This removes the official repository listing, the source Agent in the system tenant, and the corresponding server-side Bundle files. Agent copies already created in regular tenants are not deleted.

💡 Need Help

Browse the FAQ for common install issues
Drop questions in our Discord community
File bugs or feature ideas in GitHub Issues

🔧 Build from Source

Want to build from source or add new features? Check the Docker Build Guide for step-by-step instructions.

For detailed setup instructions and customization options, see our Developer Guide.

Agent Development

Agent Configuration

Local Tools

Agent Evaluation

Tools Integration

Integration-In (Inbound)

Integration-Out (Outbound)

Docker Installation & Deployment

🎯 Prerequisites

🚀 Quick Start

Online Deployment

1. Download and Setup

2. Deployment Options

HTTPS (Optional)

⚠️ Important Notes

Offline Deployment

Access Your Installation

🏗️ Service Architecture

💾 Data Persistence

Uninstall Docker Deployment

🔌 Port Mapping

🔧 Advanced Configuration

Monitoring Configuration

CAS Integration with ModelEngine

Northbound Interface Configuration (NORTHBOUND_EXTERNAL_URL)

🤖 Official Agent Deployment

Prerequisites

Interactive Deployment

Using Official Agents After Deployment

Verification

Delete an Official Agent

💡 Need Help

🔧 Build from Source

Agent Configuration

Local Tools

Agent Evaluation

Docker Installation & Deployment ​

🎯 Prerequisites ​

🚀 Quick Start ​

Online Deployment ​

1. Download and Setup ​

2. Deployment Options ​

HTTPS (Optional) ​

⚠️ Important Notes ​

Offline Deployment ​

Access Your Installation ​

🏗️ Service Architecture ​

💾 Data Persistence ​

Uninstall Docker Deployment ​

🔌 Port Mapping ​

🔧 Advanced Configuration ​

Monitoring Configuration ​

OAuth Login Configuration ​

CAS Login Configuration ​

CAS Integration with ModelEngine ​

Northbound Interface Configuration (NORTHBOUND_EXTERNAL_URL) ​

🤖 Official Agent Deployment ​

Prerequisites ​

Interactive Deployment ​

Using Official Agents After Deployment ​

Verification ​

Delete an Official Agent ​

💡 Need Help ​

🔧 Build from Source ​

Docker Installation & Deployment

🎯 Prerequisites

🚀 Quick Start

Online Deployment

1. Download and Setup

2. Deployment Options

HTTPS (Optional)

⚠️ Important Notes

Offline Deployment

Access Your Installation

🏗️ Service Architecture

💾 Data Persistence

Uninstall Docker Deployment

🔌 Port Mapping

🔧 Advanced Configuration

Monitoring Configuration

OAuth Login Configuration

CAS Login Configuration

CAS Integration with ModelEngine

Northbound Interface Configuration (NORTHBOUND_EXTERNAL_URL)

🤖 Official Agent Deployment

Prerequisites

Interactive Deployment

Using Official Agents After Deployment

Verification

Delete an Official Agent

💡 Need Help

🔧 Build from Source