Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Manage your notification preferences to stay informed about the health and performance of your Capsules.
Configure which alerts you want to receive within the Code Capsules platform. Toggle individual notification types on or off based on your monitoring needs.
Set up email alerts to receive notifications outside the platform. You can enable or disable email notifications for the same events as in-app notifications.
Available notification types include:
Capsule Not Running: When a Capsule crashes or stops running.
Killed by OOM: When a Capsule runs out of memory.
High CPU Usage: When CPU usage exceeds 80%.
High Memory Usage: When memory usage exceeds 80%.
Use the Enable All or Disable All buttons to quickly configure all notifications.
Click Save Preferences to apply your changes.
You can allocate more resources to a Capsule as your application's traffic and computational needs change.
View the scaling options available for your Capsule in the Scale tab of the Capsule dashboard. To adjust the allocated resources, click Edit in the Capsule Capacity section.
Use the sliders to configure the Capsule's resources, then click Save.
Manage your notification preferences to stay informed about your Capsule's health and performance.
Configure which alerts you want to receive within the Code Capsules platform. Toggle individual notification types on or off based on your monitoring needs.
Set up email alerts to receive notifications outside the platform. You can enable or disable email notifications for the same events as in-app notifications.
Available notification types include:
Capsule Not Running - Alert when your capsule crashes or stops
Killed by OOM - Notify when your capsule runs out of memory
High CPU Usage - Alert when CPU usage exceeds 80%
High Memory Usage - Notify when memory usage exceeds 80%
Use "Enable All" or "Disable All" buttons to quickly configure all notifications, then click "Save Preferences" to apply your changes.
Manage your notification preferences to stay informed about your Capsule's health and performance.
Configure which alerts you want to receive within the Code Capsules platform. Toggle individual notification types on or off based on your monitoring needs.
Set up email alerts to receive notifications outside the platform. You can enable or disable email notifications for the same events as in-app notifications.
Available notification types include:
Capsule Not Running - Alert when your capsule crashes or stops
Killed by OOM - Notify when your capsule runs out of memory
High CPU Usage - Alert when CPU usage exceeds 80%
High Memory Usage - Notify when memory usage exceeds 80%
Use "Enable All" or "Disable All" buttons to quickly configure all notifications, then click "Save Preferences" to apply your changes.
It is possible to allocate more resources to your Capsule depending on how much traffic your application will be getting and its computational needs. To view the different scaling options available for your Capsule, navigate to the "Scale" tab while on your Capsule's dashboard, and click the "Edit" button in the "Capsule Capacity" section.
Change the allocated resource for the Capsule with the sliders. Click "Save" when done.
It is possible to allocate more resources to your Capsule depending on how much traffic your application will be getting and its computational needs. To view the different scaling options available for your Capsule, navigate to the "Scale" tab while on your Capsule's dashboard, and click the "Edit" button in the "Capsule Capacity" section.
Change the allocated resource for the Capsule with the sliders. Click "Save" when done.
A Capsule can write to a local file system, but those files will not persist after the Capsule is restarted.
A Capsule can be thought of as a computational process that can be started and restarted. When a Capsule is started, it receives a fresh copy of the code from a GitHub repository. You can write to a Capsule in a local file system, but that file system will also start afresh when the code restarts and pulls from the GitHub repository again, so any files written to that file system will not persist when the Capsule is restarted automatically.
Instead, to have the data persist, we recommend using an external database.
Take a look at our guide to for more information.
Toggle the switch next to the backup schedule you want to use:
Daily Backup: Creates backups every day
Weekly Backup: Creates backups every week
Monthly Backup: Creates backups every month
Code Capsules retains backups based on your selected schedule and automatically deletes older backups as new ones are created.
The Backups section in the right-hand panel lists all completed backups. You can restore and manage backup files here.
Backup storage costs $0.50/GB.
The Project Path specifies the path to your code. The default is /, which works for most projects.
The Network Port is the port your app runs on. Your app must be configured to listen on this port. The default is 3000.
Use the Run Command field to specify how to start your app. Leave this field empty to use the default command for the Capsule type, or enter a custom command:
Python: python app.py
Node.js: npm start
Ruby: ruby app.rb
Each Backend Capsule is automatically assigned an APP_URL environment variable that stores its public URL.
To view environment variable values, click show in the top-right corner of the table.
To add or edit custom variables:
Click Key/Val Editor or Text Editor in the top-right corner.
Enter or update the variable’s Name and Value.
Click Save to apply your changes.
In the Data capsules section, click the View button next to a Database Capsule to see its connection details.
Click + next to the Connection string variable to create a DATABASE_URL environment variable in your Backend Capsule. Your application will use this variable to connect to and use the services provided by the Database Capsule.
Click Bind next to the Persistent Storage Capsule to attach it to your Backend Capsule.
During the bind process, Code Capsules creates a PERSISTENT_STORAGE_DIR environment variable that tells your Backend Capsule where to access the Persistent Storage Capsule.
High Data Usage: When data usage exceeds 80%.
CPU Throttle: When CPU is being throttled.
High Data Usage - Alert when data usage exceeds 80%
CPU Throttle - Notify when CPU is being throttled
High Data Usage - Alert when data usage exceeds 80%
CPU Throttle - Notify when CPU is being throttled
Each Capsule tracks its usage data and you can view this information by opening the "Metrics" tab on your Capsule's page.
Django + MySQL
Flask + MySQL
Java + MySQL
Django + MongoDB
Express + MongoDB
Flask + MongoDB
Host
Port
Database name
Username
Password
Connection string
To change the name of the Capsule, click Edit next to the Capsule name in the Capsule Details section.
Toggle on Public Access to allow access to the database from outside your Space.
When Public Access is toggled on, Code Capsules generates a public connection string that you can use to connect to the database.
Additional MySQL configuration is available in the Config tab of MySQL Capsules.
In the MySQL Configuration section, click Edit to select SQL modes for your MySQL server.
SQL modes determine how MySQL handles queries and data validation. Common options include:
STRICT_TRANS_TABLES - Enables strict mode for transactional tables
NO_ZERO_DATE - Prevents the use of invalid date values
ONLY_FULL_GROUP_BY - Requires GROUP BY to list all selected columns
Toggle "Public Access" in the "Public Access" section to allow connections from outside your Space.
This is disabled by default for security.
When Public Access is enabled, you can connect to your storage using WebDAV.
Click "show" in the "WebDAV Connection Information" section to view:
WebDAV Server URL
Username
Password
Open Finder
Click on "Go" in the menu bar and select "Connect to Server"
Enter the WebDAV server URL in the following format: https://server-address
Click "Connect"
Enter the username and password when prompted
The WebDAV server will now appear as a mounted drive in Finder
Open File Explorer
Right click on "This PC" in the sidebar
Click on "Add a network location"
Click "Next" in the wizard until prompted to enter the "Internet or network address"
Enter the WebDAV server URL in the following format: https://server-address
Enter the username and password when prompted
Complete the setup wizard
The WebDAV server will now appear as a mapped drive in File Explorer
Open your file manager (e.g., Nautilus, Dolphin, Thunar)
In your address bar enter the WebDAV server URL in the following format:
davs://server-address for Nautilus and Thunar
webdavs://@server-address for Dolphin
Enter the username and password when prompted
The WebDAV server will now appear as a mounted drive in your file manager
For Capsules that serve web traffic, open the Access Logs tab to view HTTP request logs.
Python
Django
Flask
Express.js
Java
Go
Caddy Docker Site
Docker Laravel App
Docker PHP App
Flask Docker App
Backend Deployment Guides
Manage your notification preferences to stay informed about your Capsule's health and performance.
Configure which alerts you want to receive within the Code Capsules platform. Toggle individual notification types on or off based on your monitoring needs.
Set up email alerts to receive notifications outside the platform. You can enable or disable email notifications for the same events as in-app notifications.
Available notification types include:
Capsule Not Running - Alert when your capsule crashes or stops
Killed by OOM - Notify when your capsule runs out of memory
High CPU Usage - Alert when CPU usage exceeds 80%
High Memory Usage - Notify when memory usage exceeds 80%
Use "Enable All" or "Disable All" buttons to quickly configure all notifications, then click "Save Preferences" to apply your changes.
It is possible to allocate more resources to your Capsule depending on how much traffic your application will be getting and its computational needs. To view the different scaling options available for your Capsule, navigate to the "Scale" tab while on your Capsule's dashboard, and click the "Edit" button in the "Capsule Capacity" section.
Change the allocated resource for the Capsule with the sliders. Click "Save" when done.
Manage your notification preferences to stay informed about your Capsule's health and performance.
Configure which alerts you want to receive within the Code Capsules platform. Toggle individual notification types on or off based on your monitoring needs.
Set up email alerts to receive notifications outside the platform. You can enable or disable email notifications for the same events as in-app notifications.
Available notification types include:
Capsule Not Running - Alert when your capsule crashes or stops
Killed by OOM - Notify when your capsule runs out of memory
High CPU Usage - Alert when CPU usage exceeds 80%
High Memory Usage - Notify when memory usage exceeds 80%
Use "Enable All" or "Disable All" buttons to quickly configure all notifications, then click "Save Preferences" to apply your changes.
Each Capsule tracks its usage data and you can view this information by opening the "Metrics" tab on your Capsule's page.
Each Capsule tracks its usage data. View this information by opening the Metrics tab on the Capsule's page.
Each Capsule tracks its usage data and you can view this information by opening the "Metrics" tab on your Capsule's page.
You can allocate more resources to a Capsule as your application's traffic and computational needs change.
View the scaling options available for your Capsule in the Scale tab of the Capsule dashboard. To adjust the allocated resources, click Edit in the Capsule Capacity section.
Use the sliders to configure the Capsule's resources, then click Save.
Click "Edit" in the "Wordpress Config" section to edit the name of your WordPress database. The default is app.
Your WordPress Capsule needs to connect to a Peristent Storage Capsule. Click "Edit" in the "Wordpress Config" section to select a Peristent Storage Capsule from your Space.
WordPress Capsules automatically get these environment variables:
WORDPRESS_DB_HOST - Database server location
WORDPRESS_DB_NAME - Database name
WORDPRESS_DB_USER - Database username
WORDPRESS_DB_PASSWORD - Database password
APP_URL - Your site's public URL
To view variable values, click "show" in the "Environment Variables" section.
To add custom variables:
Click "Key/Val Editor" or "Text Editor" in the "Environment Variables" section
Edit the variable "Name" and "Value"
Click "Save"
Add custom PHP settings if needed, like upload sizes or memory limits.
Leave the field empty to use default settings.
Click "Edit" in the "Capsule Parameters" section to set your build command. The default is Auto which automatically detects and runs your build process.
Click "Edit" in the "Capsule Parameters" section to set where your built files end up. Leave as / if you're not using a build process.
Frontend Capsules automatically get these environment variables:
APP_URL - Your capsule's public URL
To view variable values, click "show" in the "Environment Variables" section.
To add custom variables:
Click "Key/Val Editor" or "Text Editor" in the "Environment Variables" section
Edit the variable "Name" and "Value"
Click "Save"
Set up email alerts to receive notifications outside the platform. You can enable or disable email notifications for the same events as in-app notifications.
Available notification types include:
Capsule Not Running - Alert when your capsule crashes or stops
Killed by OOM - Notify when your capsule runs out of memory
High CPU Usage - Alert when CPU usage exceeds 80%
High Memory Usage - Notify when memory usage exceeds 80%
High Data Usage - Alert when data usage exceeds 80%
CPU Throttle - Notify when CPU is being throttled
Use "Enable All" or "Disable All" buttons to quickly configure all notifications, then click "Save Preferences" to apply your changes.
High Data Usage - Alert when data usage exceeds 80%
CPU Throttle - Notify when CPU is being throttled
High Data Usage - Alert when data usage exceeds 80%
CPU Throttle - Notify when CPU is being throttled
It is possible to allocate more resources to your Capsule depending on how much traffic your application will be getting and its computational needs. To view the different scaling options available for your Capsule, navigate to the "Scale" tab while on your Capsule's dashboard, and click the "Edit" button in the "Capsule Capacity" section.
Change the allocated resource for the Capsule with the sliders. Click "Save" when done.
For Capsules that serve web traffic, navigate to the "Access Logs" tab to view HTTP request logs.
For Capsules that serve web traffic, navigate to the "Access Logs" tab to view HTTP request logs.
Postgres
Redis
Database Deployment Guides
WordPress Site
Quickstart guide to running WordPress on a dedicated Capsule.
Deploy a WordPress application and learn how to host a content management system on Code Capsules.
To follow this guide, you'll need a Code Capsules account. WordPress can be downloaded and deployed automatically or you can connect your Capsule to Wordpress hosted on a GitHub repository.
Before creating your WordPress capsule, you'll need a Team and a Space. You can follow these guides to learn how to create and .
If you already have a Team and Space set up, log in to your Code Capsules account. On the dashboard, click the yellow + on the bottom left of the screen then click "New Capsule".
A provides the server for hosting an application on Code Capsules.
To create a Wordpress Capsule first choose "WordPress" as the Capsule type, as well as your Team, and Space.
Next choose your payment plan, or create a custom plan.
A Wordpress Capsule requires a connection to a MySQL Database Capsule as well as a Persistent Storage Capsule. Either select a previosuly created instance of each from the dropdowns, or click the yellow + next to each and follow the prompts for creating each Capsule. Click "Create Capsule".
To automatically download and deploy a Wordpress version on Code Capsules:
Select the "Default" deployment type from the dropdown
Choose your WordPress version
Click "Next"
To deploy WordPress from your version control repository:
Select the "Git Managed" deployment type
Select a repository
Select the branch to deploy from
Click "Next"
You can read more about connecting your account to a version control provider in .
Code Capsules will automatically build and deploy your WordPress application. You can view the build log by selecting the "Logs" tab to monitor the deployment progress.
Once the build is complete, click the URL link in the "Details" tab, to access your WordPress site.
When you first visit your WordPress site, you'll see the installation screen:
Enter your site title.
Create an admin username.
Set a strong password.
Provide your email address.
After installation, you'll see the WordPress admin dashboard and can begin customizing your site.
Configure an Agent Capsule in the Config tab.
Click Edit in the Capsule Parameters section to set the Capsule's project path, network port, and run command.
The Project Path specifies the path to your code. The default is /, which works for most projects.
The Network Port is the port your app runs on. Your app must be configured to listen on this port. The default is 3000.
Use the Run Command field to specify how to start your app. Leave this field empty to use the default command for the Capsule type, or enter a custom command:
Python: python app.py
Node.js: npm start
Click Edit in the Agent Config section to set the Capsule's provider, model, and API key.
The Provider specifies the public AI provider to use for the capsule. This will expose a PROVIDER_NAME environment variable in the runtime of the capsule. Among a few pre-defined options, there is also the ability to set a Custom provider name, which your altered codebase will need to cater for.
The Model specifies the AI model to be used during the agent runtime. This will expose a PROVIDER_MODEL environment variable in the runtime of the capsule. Among a few pre-defined options per provider, there is also the ability to set a Custom model name, which your altered codebase will need to cater for.
The API Key specified the key as provided by the AI Provider. This is issued outside of Code Capsules but are necessary for the agent to work, and will expose a PROVIDER_API_KEY environment variable in the runtime of the capsule.
Each Agent Capsule is automatically assigned an APP_URL environment variable that stores its public URL.
To view environment variable values, click show in the top-right corner of the table.
To add or edit custom variables:
Click Key/Val Editor or Text Editor in the top-right corner.
Enter or update the variable’s Name and Value.
Click Save to apply your changes.
In the Data capsules section, click the View button next to a Database Capsule to see its connection details.
Click + next to the Connection string variable to create a DATABASE_URL environment variable in your Agent Capsule. Your application will use this variable to connect to and use the services provided by the Database Capsule.
Click Bind next to the Persistent Storage Capsule to attach it to your Agent Capsule.
During the bind process, Code Capsules creates a PERSISTENT_STORAGE_DIR environment variable that tells your Agent Capsule where to access the Persistent Storage Capsule.
Each Capsule tracks its usage data. View this information by opening the Metrics tab on the Capsule's page.
Deploy a configurable Agent Capsule on Code Capsules.
To follow this guide, you'll need a Code Capsules account.
Before creating your Agent Capsule, you'll need a Team and a Space. You can follow these guides to learn how to create and .
If you already have a Team and Space set up, log in to your Code Capsules account. On the dashboard, click the yellow + on the bottom left of the screen then click "New Capsule".
A provides the server for hosting an application on Code Capsules.
To create an Agent Capsule first choose "AI Agent" as the Capsule type, as well as your Team, and Space.
Next choose your payment plan, or create a custom plan.
Code Capsules provides templates (see ) as a baseline for creating your AI Agent. When creating the Agent Capsule, you can select if your codebase comes from a template repo. In this case, you will be asked to enter a provider, model, and API key for a public AI provider, such as Google Gemini or Anthropic. When registering with one of these providers, they should provide an API key to access their public API's. Once the capsule is created, the templates will make use of this information via environment variables, which are automatically set up for you upon capsule creation. You can learn more about how these templates make use of these environment variables .
Code Capsules will automatically build and deploy your Agent Capsule. You can view the build log by selecting the "Build logs" tab to monitor the deployment progress.
Once the build is complete, use the Chat tab to interface with your newly running agent.
Each Capsule tracks its usage data and you can view this information by opening the "Metrics" tab on your Capsule's page.
This guide walks you through migrating a database using an Express app and a MySQL Capsule.
You might find our guides on and helpful.
To install db-migrate, first clone your GitHub repository with the following command (make sure to replace the username and repository name with your own):
git clone https://github.com/git_username/repository_name.git
db-migrateTo use migration commands, install both db-migrate and db-migrate-mysql with the following commands:
npm install -g db-migratenpm i db-migrate-mysql
The db-migrate package connects to a database through a database.json file.
Create a file called database.json in your root directory and populate it with your database information. The example below shows how to connect to both a local database called "dev" and a MySQL Data Capsule called "prod" (be sure to replace the database information with your own):
Here we also add"sql-file": true to ensure that database migrations run using SQL files, which we'll create in the next step.
Find the database URL for a MySQL Data Capsule in the Config tab of a Backend Capsule:
You can also access the database URL using an environment variable as follows:
"prod": {"ENV":"DATABASE_URL"},
Run the following command to create a folder to store migrations:
db-migrate create insert_unique_name --sql-file
The folder should contain three files:
MySQL queries are stored in the two generated SQL files: One named with an up suffix and the other with a down suffix.
Insert the following SQL query into the down file to remove a row from the database:
Insert the following SQL query into the up file to insert a row into the database:
Add your own MySQL queries to these SQL files to define custom database migrations.
In the root directory of the project, update the "scripts" section in the package.json file as follows:
Modify these scripts to suit your developer and production environments.
The migration scripts shown here are designed to be used on Code Capsules or in a developer environment.
To run these migrations in a production environment, update the Capsule's Run Command to execute the migration scripts.
Edit the Run Command in the Config tab of the Backend Capsule.
Finally, commit and push your changes to your GitHub repository to update the codebase and trigger the migrations.
View migration activity in the Backend Capsule's Logs tab. The output will look similar to this:
For Capsules that serve web traffic, navigate to the "Access Logs" tab to view HTTP request logs.
React
Angular
Vue
Next.js
Svelte
Static HTML
HTML5UP Template
Bootstrap
Frontend Deployment Guides
You need persistent storage for your application, but you don't want a full-blown database.
This guide will show you how to create a persistent storage Data Capsule that you can use with backend applications running on Code Capsules.
A Persistent Storage Capsule works like a virtual hard drive in the cloud. The key benefit is that you can attach multiple Backend or Docker Capsules to the same Persistent Storage Capsule, enabling them to share data and scale horizontally or vertically.
To set up persistent file storage, you'll first create a Persistent Storage Capsule, then bind it to a Backend Capsule.
Log in to your Code Capsules account and navigate to the Space where you want to create a Data Capsule.
Click the yellow + button on the bottom-left corner of the dashboard. Select New Capsule and then Persistent Storage from the dropdown.
Select your payment method, then click Create Capsule.
You need to bind the Storage Capsule to a Backend Capsule hosted on Code Capsules before you can connect to and use it.
Navigate to the Backend Capsule and open the Config tab. Scroll down to the Bind Data Capsule section, where your recently created Storage Capsule is listed.
Click Bind to bind the Capsules.
During the bind process, Code Capsules creates a PERSISTENT_STORAGE_DIR environment variable that your Backend Capsule will use to access the Storage Capsule.
When the two Capsules are bound, scroll to the top of the Config tab to view the value of the variable.
Now you can use this environment variable in your code to read and write to the Storage Capsule. Copy the value of the PERSISTENT_STORAGE_DIR variable and assign it to the db_directory variable. Alternatively, reference it directly using os.getenv in Python or process.env in Node.js.
If you're using Python in your Backend Capsule, use the following code to connect to the Storage Capsule:
If you're using Node.js in your Backend Capsule, use the following code to connect to the Storage Capsule:
By default, you can't browse files and folders in your Persistent Storage Capsule without building your own file browser. To solve this, Code Capsules provides native WebDAV access.
To enable file browsing:
Navigate to your Persistent Storage Capsule
Go to the Details tab
Toggle Public Access to Enabled
Enabling this setting doesn't make your files publicly accessible on the internet. They are served over the WebDAV protocol and require authentication credentials to access.
Open Finder
Click on Go in the menu bar and select Connect to Server
Enter the WebDAV server URL in the following format: https://server-address
Click Connect
The WebDAV server will now appear as a mounted drive in Finder.
Here you can see the files inside a WordPress Capsule accessed locally through Finder in macOS.
Open File Explorer
Right click on This PC in the sidebar
Click Add a network location
Click Next in the wizard until prompted to enter the Internet or network address
The WebDAV server will now appear as a mapped drive in File Explorer.
Open your file manager (for example, Nautilus, Dolphin, or Thunar)
In your address bar, enter the WebDAV server URL in the following format:
davs://server-address for Nautilus and Thunar
webdavs://@server-address
The WebDAV server will now appear as a drive in your file manager.
Code Capsules provides an integrated chat window for Agent Capsules. In order for this to be fully functional, there are a few endpoints which the API needs to expose.
The deployed codebase needs to expose a few endpoints, each with their own pre-described payload. Data is always returned in the ApiResponse format. Errors are returned in the Error format.
Below describes the endpoints required to use the integrated chat window:
*Only one of these are required
All of the above endpoints will also be passed the following headers. This allows for some simple security when testing the agent using the integrated chat window:
A Procfile tells the Backend Capsule which processes to run and how to start them. While Procfiles aren't required on Code Capsules, you can provide one to define custom startup behavior for your application.
Instead of using a Procfile, you can specify build and run commands directly in the Code Capsules UI. For example, the screenshot below shows how to enter a run command for a Node.js application.
A Procfile is a plain text file. It must be named exactly Procfile, with no extensions (like .txt
"dev": {
"driver": "mysql",
"user": "root",
"database": "database_name",
"password": "my_password"
},
"prod": "Insert Your Database URL here",
"sql-file": true
}ALTER TABLE table_name
DROP COLUMN drop_column_name; ALTER TABLE table_name
ADD new_row_name datatype;"scripts": {
"start": "node ./bin/www",
"migratedev": "node node_modules/db-migrate/bin/db-migrate up -e dev",
"migrate-prod-up": "node node_modules/db-migrate/bin/db-migrate up -e prod",
"migrate-prod-down": "node node_modules/db-migrate/bin/db-migrate down -e prod"
}> node node_modules/db-migrate/bin/db-migrate up -e prod
> [email protected] migrate-prod-up
);
FirstName varchar(255)
LastName varchar(255),
PersonID int,
received data: CREATE TABLE user (
[INFO] Processed migration 20220523135622-migration_name
[INFO] DoneEnter the username and password when prompted
Enter the WebDAV server URL in the following format: https://server-address
Enter the username and password when prompted
Complete the setup wizard
Enter the username and password when prompted
.pyprocfileThe Procfile must be placed in the root directory of your project. It won't work in any other location.
The Procfile defines the processes that a Backend Capsule must run before deploying a backend application. Common process types include web, worker, and clock.
Each process type must be paired with the command that should be used to run it. You can use the command to specify the port the process must run on and other process-specific options.
The Procfile uses a key-value format, with each line defining a process type and its corresponding command, as shown below:
Code Capsules only requires a Procfile for Python applications. Here is an example of how a Procfile for a Flask application might look:
Express and Java applications don't need a Procfile to be deployed. The Backend Capsule automatically detects the application type and runs the appropriate processes.
import os
db_directory = os.getenv('PERSISTENT_STORAGE_DIR')
### Do something with the db_directory variable here
file_to_write = os.path.join(db_directory, "test.txt")
file1 = open(file_to_write, "w")
file1.write("File writing test")
file1.close()
db_directory = process.env.PERSISTENT_STORAGE_DIR
const fs = require('fs')
const content = 'Some content!'
// Do something with the db_directory variable here
fs.writeFile(db_directory + '/test.txt', content, err => {
if (err) {
console.error(err)
return
}
//file written successfully
})
<process type>: <command>web: python3 -m flask run --host=0.0.0.0 --port=$PORTPOST
/api/chat/message
Send a message to the agent with an instant response.
Yes*
POST
/api/chat/message/stream
Send a message to the agent, streaming back the response.
Yes*
GET
/api/chat/history
Get the chat history for the user.
Yes
X-CC-API-KEY
This value will be the value as generated in the INTERNAL_API_KEY environment variable on creation of the Agent capsule.
No
X-CC-EMAIL
This value will be the email of the user who has logged into Code Capsules, allowing for testing with unique chat sessions and chat history.
No
Each application deployed on Code Capsules is assigned a default domain in the format capsulename.xxxx.codecapsules.co.za.
At no additional cost, you can configure Code Capsules to use a custom domain you own (like example.com) instead of the default domain.
The Domains tab contains all information about a Capsule's domain, including the option to add a custom domain.
To add a new custom domain, click the yellow + button in the top-right corner of the dashboard.
Copy and save the Static IP address.
Click the Add Custom Domain link and enter your custom domain in the Domain Name field.
Ensure you enter only a root domain. Do not include a subdomain. A root domain contains only a domain name and top-level domain, for example, example.com. See the below.
Click Create Domain.
Next, you need to create an A record with your domain registrar for the custom domain you've purchased.
Log in to your domain registrar's dashboard and locate the DNS settings for your custom domain.
Retrieve the static IP address you previously copied and saved and add an A record pointing to it. Your A record entry may look something like this:
Where:
@ refers to your root domain (for example, example.com).
provided-IP-Address is the static IP address from Code Capsules.
Consult your domain registrar's documentation for specific instructions on adding A records to your domain.
Before adding a subdomain, make sure your custom domain has an pointing to your application on Code Capsules.
To add a new subdomain, click the yellow + button in the top-right corner of the dashboard.
Click the Add Custom Domain link and enter the subdomain to create in the Domain Name field.
Click Create Domain.
Next, you need to create a CNAME record with your domain registrar for the subdomain you added.
Log in to your registrar's dashboard and navigate to the DNS settings for your domain. Add a CNAME record for the subdomain. Your CNAME record entry may look something like this:
Where:
subdomain is the subdomain you're adding, for example, app or www.
your-root-domain is your root domain that contains an A record routing to your application on Code Capsules.
Consult your domain registrar's documentation for specific instructions on adding CNAME records to your domain.
To remove a domain or subdomain from a Capsule, go to the Capsule's Domains tab.
All associated domains and subdomains are listed in the right-hand panel. To remove one, click the trash can icon next to the domain or subdomain.
Removing a custom domain or subdomain does not update or delete its DNS records.
If you remove a root domain, update the A record with your domain registrar to remove or change the IP address.
If you remove a subdomain, delete the corresponding CNAME record from your DNS settings.
Uniform Resource Locator (URL): A web address used to locate a resource on the internet. URLs typically include a subdomain, a second-level domain, and a top-level domain.
Subdomain: The portion of a URL before the main domain name, most commonly www. Subdomains are often used to organize different services or sections of a website (for example, hr.myapplication.com might route users to your company’s human resources portal).
Second-level domain (SLD): The core name of the domain, located between the subdomain and the TLD. In www.example.com
Domain Registrar: A company that sells and manages domains.
A Record: Routes a domain (for example, example.com) to an IP address (for example, 123.456.567.8).
Wildcard Subdomain: Routes all undefined subdomains of a domain to a specific destination. For example, if the *.example.com wildcard subdomain points to example.com
Hypertext Transfer Protocol (HTTP): Protocol used to transfer data from a server (such as a web application) to a client (such as your web browser).
Hypertext Transfer Protocol Secure (HTTPS): A secure version of HTTP that encrypts data transferred between the server and client for better security.
Secure Sockets Layer (SSL) Certificate: Authenticates a domain and enables encrypted communication between a server and a client via HTTPS (for example, https://www.example.com).
Code Capsules provides a variety of agent template repos for you to use as the base for your Agent Capsule.
Each template comes with a tutorial on how to successfully deploy the template, and can be accessed from our GitHub pages. See the list of available templates below:
exampleTop-level domain (TLD): The final part of the domain name, such as .com, .org, or .co.za. TLDs often indicate the purpose or location of a website, for example, .de typically signals a website based in Germany, while .org is commonly used by non-profit organizations.
Root Domain: The combination of the SLD and TLD, excluding any subdomains, for example, example.com.
info.example.com123.example.comexample.comCNAME Record: Also known as an "alias", routes a subdomain to another domain name (for example, mail.example.com -> mail.google.com). Unlike A records, which point to IP addresses, CNAME records point to domain names.
A Record
@
provided-IP-Address
CNAME
subdomain
your-root-domain
Google Calendar Agent
Base Agent functionality (forked off Base Agent)
Add events to Google Calendar
Get a list of events from Google Calendar
Each template consists of the same base architecture, containing the following:
A list of endpoints: required for interaction with the Code Capsules Agent Chat tab
A memory store: allows for the agent to retain overall memory. Useful when the agent needs to store some memory "globally" (i.e. will be applied across all prompts). By default, a connection attempt will be made to a Redis instance, but will fall back to an in-memory store if unavailable
A vector store: allows for the agent to gain context through RAG. Using the prescribed endpoints, one can add context using text or a URL. By default, a connection attempt will be made to a Redis instance, but will fall back to an in-memory vector store if unavailable
Follow the following procedure to begin creating your new agent. In this example, we will use Google as the provider, but there are other options available.
If you already have a free or paid tier Google AI Studio account and API key, you can move to step 3, else continue to step 2.
Follow the following guidelines to create a new Google Gemini API key: https://ai.google.dev/gemini-api/docs/api-key. Make sure to copy your key somewhere safe as it will be needed later.
Navigate to one of the template repositories on GitHub as described above. If you are new to AI Agent development, it is recommended to start with a simple Base Agent.
Using the template repo, create your own new repository by following the steps here: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template.
Follow the setup steps for the template in the relevant README.md file which can be found in the same GitHub repository.
, linking your newly created repo, and adding your provider, model, and API key when requested.
Once the capsule is built, navigate to the Chat page - ask your newly deployed Agent Capsule anything you'd like! Remember: if you are using a template, the agent will most likely be confined to a specific purpose, so be sure to read the README.md file for more information on its capabilities.
You can now modify your codebase however you'd like to include new tools, context, and more.
Agent Capsule templates have been built with the capabilities of using either a Redis or in-memory vector store. When using the in-memory option (i.e. no Redis Capsule is linked), it is recommended to scale the Agent Capsule to the following in order to ensure optimal performance:
CPU 25%
Memory 1GB
Replicas 1
To do this, visit the Agent Capsule page.
Each template has been written to use memory as a vector store for RAG. However, the templates also cater for connections to a Redis instance as its vector store. In order to set this up, follow the following steps:
Create a Redis Capsule.
Copy the Connection String in the Details tab of your Redis Capsule.
Navigate to the Config page of your Agent Capsule.
On the Environment Variables section (on the right-hand side), click the Text Editor.
Add the following at the bottom of the Environment Variables list:
Wait for the Agent Capsule to restart - it should now use the Redis Capsule as its vector store.
In order to test RAG functionality, do the following:
Make a call to the following endpoint:
Navigate to the Agent Capsule Chat tab.
Ask the agent the following question:
The agent should respond with something along the lines of:
All agent templates come with pre-written OpenAPI documentation. In order to access this documentation, an environment variable needs to be added to the Agent Capsule. Follow the following steps to do so:
Open Code Capsules.
Navigate to the Config page of your Agent Capsule.
On the right-hand side, in the Environment Variables section, click 'Text Editor'.
Paste the following into the bottom of the editor:
Click 'Save'.
Wait for the Agent Capsule to restart.
Navigate to the 'Details' page of your Agent Capsule.
Copy the 'Public URL' link.
In a new browser tab, paste the URL and append /api-docs to the end of the URL.
Once the page is loaded, you should see some fully functional OpenAPI documentation for your agent, unique to your selected agent template.
These documents are served directly from the src/docs/swagger.json file in the agent repo.
If you've followed the above steps to create an Agent Capsule, you're probably now looking into how you can add your own tools, context, and other customisation. Follow the topics below to investigate how to do this.
Changing the public AI provider and model through the Code Capsules site is easy. You can do this by navigating to the Config page for the Agent Capsule. Here, you can edit the Agent Config to change these details to cater your needs. After the changes are applied, the Agent Capsule will restart and use your newly provided configuration. See more here.
Each agent template comes with a pre-written system prompt found in the src/modules/agent/config/system-prompt.ts file. This will provide your agent with a base prompt from which it will build it's context.
It is important to note that changing this prompt will require you to push your changes to the relevant GitHub repo and branch, and ensuring that a new build is started in Code Capsules. Once the build is complete, your changes will be ready for use.
Adding a new tool to your agent has been made easy with the simple layout structure built into the agent templates. Follow these simple steps to add a new tool, with a side-by-side example of creating a new getWeather tool.
Navigate to the /src/modules/agent/tools/implementations folder.
Create a new file to describe your new tool.
New file:
src/modules/agent/tools/implementations/my-new-tool.tool.ts
New file:
src/modules/agent/tools/implementations/get-weather.tool.ts
In your new file, add code with the following structure, replacing where necessary:
In the src/modules/agent/tools/implementations/index.ts file, export your new tool.
In the src/modules/agent/tools/tools-manager.ts file, add your new tool to the list in the constructor.
(Optional) Add new System Prompt context in the src/modules/agent/config/system-prompt.ts file.
Push your code.
Code Capsules, if configured to do so, will automatically rebuild your Agent Capsule. Once complete, navigate to your Chat page and ask the agent a question.
Base Agent
Basic agent communication
RAG (context) functionality
Telegram Bot Agent
Base Agent functionality (forked off Base Agent)
Runs a Telegram bot which calls the agent for communication
curl -L \
--request POST \
--url '{agent_capsule_public_url}/api/context/text' \
--header 'Content-Type: application/json' \
--data '{
"text": "George is the king of the jungle. He likes hats and eats snails."
}'const response = await fetch('{agent_capsule_public_url}/api/context/text', {
method: 'POST',
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
"text": "George is the king of the jungle. He likes hats and eats snails."
})
});
const data = await response.json();import { z } from "zod";
import { tool } from "langchain";
import { BaseTool } from "../base.tool";
export class NewTool implements BaseTool {
public tool = tool(
async (input) => {
return `New tool with input ${input.anInputString}`;
},
{
name: "newTool",
description: "New tool with an input string",
schema: z.object({
anInputString: z.string(),
}),
}
);
}
import { z } from "zod";
import { tool } from "langchain";
import { BaseTool } from "../base.tool";
export class GetWeatherTool implements BaseTool {
public tool = tool(
async (input) => {
return `The weather in ${input.location} is sunny and 20 degrees!`;
},
{
name: "getWeather",
description: "Get the weather in a location",
schema: z.object({
location: z.string().describe("The location to get the weather for"),
}),
}
);
}
export * from "./new-tool";export * from "./get-weather.tool";this.tools.push(new NewTool());this.tools.push(new GetWeatherTool());You are a helpful assistant with access to the following tool:
newTool - a new tool which retrieves an inut string and returns the same string.
This is a very basic tool which is just for testing Agent functionality, so ensure to just fire off this tool as necessary without being concerned about input or output.
An example of a user wanting to fire this would be "Please use my newTool with the input 'Hello, friend!'"You are a helpful assistant with access to the following tool:
getWeather - a tool used to get the weather of a specific location.
This is a very basic tool which is just for testing Agent functionality, so ensure to just fire off this tool as necessary without being concerned about input or output. It only returns that the weather is sunny in the provided location, and this is what is expected.
An example of a user wanting to fire this would be "What is the weather in Tokyo today?", which should return "The weather in Tokyo is sunny and 20 degrees". This can then be formatted into a nice, unique sentence for the user.Please use my newTool with the input 'Hello, friend!'What is the weather in Tokyo today?REDIS_URL=your_copied_connection_stringWho is the king of the jungle?George is the king of the jungle. He likes hats and eats snails.SHOW_DOCUMENTATION=truegit add .
git commit -m "Added new tool"
git push origin mainSend a message to the conversational AI agent and receive a complete response. For streaming responses, use the /message/stream endpoint instead.
API key for authentication
Timestamp of the message
2025-11-07T10:30:00ZSend a message to the conversational AI agent and receive a streaming response. The response is sent as Server-Sent Events (SSE) with each chunk containing the type and content.
API key for authentication
Timestamp of the message
2025-11-07T10:30:00ZSuccessful streaming response from the AI agent
Server-Sent Events stream containing message chunks
Bad request - Message is required
Unauthorized - Invalid or missing authentication headers
Internal server error
Retrieve the complete chat history for the currently authenticated user, including all previous conversations.
API key for authentication
Chat history retrieved successfully
Unauthorized - User not authenticated or missing user information
Internal server error
Add text content to the vector store for use in RAG (Retrieval-Augmented Generation) context retrieval.
API key for authentication
The text content to be added to the vector store
Context added successfully
Bad request - Context text is required
Unauthorized - Invalid or missing authentication headers
Internal server error
Fetch content from a URL and add it to the vector store for use in RAG (Retrieval-Augmented Generation) context retrieval.
API key for authentication
The URL to fetch content from
https://example.com/articleContext added successfully
Bad request - URL is required
Unauthorized - Invalid or missing authentication headers
Internal server error
Successful response from the AI agent
Bad request - Message content is required
Unauthorized - Invalid or missing authentication headers
Internal server error
{
"data": [
{
"role": "user",
"content": [
{
"text": "Hello there"
}
],
"date": "2025-12-16T14:35:53.199Z"
}
],
"success": true
}POST /api/chat/message HTTP/1.1
Host:
X-CC-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 80
{
"content": [
{
"type": "text",
"text": "Hello there"
}
],
"date": "2025-11-07T10:30:00Z"
}POST /api/chat/message/stream HTTP/1.1
Host:
X-CC-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 80
{
"content": [
{
"type": "text",
"text": "Hello there"
}
],
"date": "2025-11-07T10:30:00Z"
}textGET /api/chat/history HTTP/1.1
Host:
X-CC-API-KEY: YOUR_API_KEY
Accept: */*
{
"data": [
{
"role": "user",
"content": [
{
"text": "Hello there"
}
],
"date": "2025-12-16T14:35:53.199Z"
}
],
"success": true
}POST /api/context/text HTTP/1.1
Host:
X-CC-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 15
{
"text": "text"
}{
"success": true
}POST /api/context/url HTTP/1.1
Host:
X-CC-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37
{
"url": "https://example.com/article"
}{
"success": true
}