Skip to main content

On-premise Agent Overview

Keep customer data in your VPC for internal tools, while keeping Superblocks always up-to-date from our cloud

note

Who can use this feature?


Organization Owners, Admins, and other users with the agents:read permission

Customers can choose between two options to deploy Superblocks:

  1. Cloud (default) - simple to get started, simple to manage. Superblocks Cloud acts as a proxy to your Integration. Superblocks never stores your customer data.
  2. On-premise Agent - your customer data never leaves your VPC. Used by organizations with specific compliance requirements. Requires deploying our light-weight open source on-premise agent.

On this page:

  1. On-premise Agent Benefits
  2. On-premise Agent Variants
  3. On-premise Agent Architecture and Data Flow
  4. Superblocks Data Storage and Access Control

On-premise agent benefits​

The on-premise agent is designed as a hybrid cloud/on-premise deployment option for organizations with sensitive data:

  • Customer data never leaves your VPC: Your customer data never leaves your network / VPC and it cannot be sent to the Superblocks Cloud.
  • Seamless updates from Superblocks Cloud: Non-sensitive data like new UI components and Integration templates are always served from the Superblocks Global Edge Network.
  • Bring your own key: The code you write is signed by your agent in your VPC meaning your code is always secure since it cannot be modified by Superblocks or a 3rd party.
  • Low Operational Overhead: Simple to manage, the agent is stateless - no database migrations, no downtime, no rollback concerns.
  • Developer Extensibility: Since the agent is open source, you can add integrations or extend it any way you see fit.
  • Simple Security Audits: The agent is open source so your Security team can audit the code directly.
  • Scalability: The agent is both horizontally and vertically scalable making it simple to manage larger workloads as you grow.

On-Premise Agent Variants​

The Superblocks On-premise Agent has two variants: the standard agent and the slim agent. The agent variants give you different levels of control over the packages included in the agent and that are available when your developers write Python and JavaScript code in their APIs.

Which variant should I use?​

If you're unsure where to start, want to get up and running quickly, or need to minimize dependencies on your DevOps team, the standard image is the way to go. The standard image includes all the same JavaScript and Python libraries included in Superblocks Cloud, so will let developers get started quickly with a bunch of useful libraries out of the box. Since devs have access to many of the libraries they may need, they won't need to come to your DevOps team to install new packages to unblock development.

The standard image is also recommended if you're a current Superblocks Cloud customer and already have tools deployed and you're not sure which packages/libraries you're developers are using.

The slim image on the other hand is ideal for organizations that have a high need for customization or have stringent security requirements where it is acceptable for the DevOps team to be involved in assisting developers with installing or upgrading necessary packages.

Unlike the standard image the slim image only includes the minimum packages required for the agent to run. Because of this, you'll have greater control over your agent's dependencies and can fully manage security patches and version upgrades on your own.

Variants​

Standard​

superblocksteam/agent:<version>
Supported Libraries​

The standard on-premise agent is the defacto Superblocks agent image. It includes:

From a functionality point of view, running workloads against this agent is akin to running workloads against the cloud agents.

How to use​

To use this agent variant, you'll set an environment variable as follows based on how you deploy your agents:

Deployment TypeEnvironment Variable
DockerSUPERBLOCKS_DOCKER_AGENT_TAG=<version>
Terraformsuperblocks_agent_image = "ghcr.io/superblocksteam/agent:<version>"
Helmimage: repository: ghcr.io/superblocksteam/agent

Slim​

superblocksteam/agent:<version>-slim
How to use​

To use this agent variant, you'll set an environment variable as follows based on how you deploy your agents:

Deployment TypeEnvironment Variable
DockerSUPERBLOCKS_DOCKER_AGENT_TAG=<version>-slim
Terraformsuperblocks_agent_image = "ghcr.io/superblocksteam/agent:<version>-slim"
Helmimage:   repository: ghcr.io/superblocksteam/agent   tag: \<version\>-slim</pre>

Building From Source​

When building the on-premise agent from source, there are four build arguments that are used to determine the variant of the agent being built:

  • SLIM_IMAGE
  • REQUIREMENTS_FILE
  • WORKER_JS_LOCK_FILE
  • WORKER_JS_SERVER_PACKAGE_JSON

If none of these arguments are specified, building the image from source will build the slim variant of the agent (i.e. the default value for all of these arguments is the slim variant value).

The following table describes the build arguments and what their respective values should be to build the desired variant from source:

ArgumentTypeValue (Standard → Slim)
SLIM_IMAGEbooleanfalse → true
REQUIREMENTS_FILEstring/app/worker.py/requirements.txt → ...-slim.txt
WORKER_JS_LOCK_FILEstringpnpm-lock.yaml → pnpm-lock-slim.yaml
WORKER_JS_SERVER_PACKAGE_JSONstringpackages/server/package.json → ...-slim.json

Descriptions:

  • SLIM_IMAGE: Sets SUPERBLOCKS_SLIM_IMAGE env var for Python worker logic
  • REQUIREMENTS_FILE: Path to Python worker requirements file
  • WORKER_JS_LOCK_FILE: Path to pnpm lock file (JS worker, relative to /app/worker.js/)
  • WORKER_JS_SERVER_PACKAGE_JSON: Path to server package’s package.json for JS worker (relative to /app/worker.js/)

Build Command​

The following command can be used to build the on-premise agent from source, setting each of the build arguments to the appropriate value for the desired variant:

$ docker build -t superblocks \
    --build-arg VERSION=$(git describe --tags --abbrev=0 --match "v*")+$(git describe --always --dirty) \
    --build-arg SLIM_IMAGE=<slim_image> \
    --build-arg REQUIREMENTS_FILE=<requirements_file> \
    --build-arg WORKER_JS_LOCK_FILE=<lock_file> \
    --build-arg WORKER_JS_SERVER_PACKAGE_JSON=<package_json_file> \
    .

Follow these instructions to create an agent key, then run the following commands to test that the newly built agent is operational:

$ docker run --rm -p 8080:8080 -e SB_AGENT_KEY=${SB_AGENT_KEY} superblocks
$ curl -s http://127.0.0.1:8080/health | jq
{
  "message": "OK",
  ...
}

On-premise agent architecture and data flow​

info

Secure Customer Data The on-premise agent ensures customer data never leaves your network and is never seen by the Superblocks server.

On-premise Agent Architecture and Data Flow

How it works​

When your developers build apps in Superblocks and write SQL statements or API calls, your customer data flows from your Database to the On-premise Agent to the browser directly; never to Superblocks Cloud. In addition, the Superblocks Cloud cannot make any inbound network calls to the customer’s network.

The Browser will call out to the Superblocks Cloud only for Authentication, Permissions, App UI Definitions and App Integration Definitions. This approach keeps Superblocks components and functionality up-to-date for your developers with each release and bug fix, without needing to upgrade the On-Premise Agent.

When the Developer is ready to go to production, they click “Deploy” (Superblocks can alternatively integrate into your version control system) and the application will be accessible on a URL.

In the deployed app, when a user clicks a button to trigger an API call, the call is routed to the On-Premise Agent and the App Integration Definition will be fetched from Superblocks Cloud (Optionally customers can connect to their version control system so API Integration Definitions are fetched directly from a branch). This round-trip restricts end users from running arbitrary APIs, only APIs from the App Integration Definition approved by Developers with the right permissions can be triggered. The On-Premise Agent will execute the API logic based on the definition and all customer data flows from the data sources to the agent to the browser directly, never leaving the customer’s network and never going to the Superblocks Cloud.

Network security​

All traffic to and from the On-premise Agent is encrypted with TLS. The On-premise Agent sets CORS so it will only accept requests that originated from Superblocks Cloud and rerouted to the agent

Bring your own key​

Before the On-premise Agent executes an API, Workflow, or Scheduled Job, it verifies the integrity of the definition so that you have confidence that the code that is running is always the code you wrote.

Agent authentication​

Authentication is enabled by default on the agent, users have to authenticate with Superblocks Cloud in order to trigger API requests via the agent. The agent will verify the auth token from the cloud and pass it along any requests to the cloud to verify permissions.

Secure agent communication​

Superblocks Cloud does not make any network requests to the Superblocks On Prem Agent. All communication between the agent and cloud is one-way and initiated from the agent. Detailed information about all network calls to and from the agent can be found here.

Data stored by Superblocks​

DataSuperblocks CloudSuperblocks On-Premise
Authentication
  • Email
  • Password
  • SSO Configuration

Configured and stored in Auth0

Same as Superblocks Cloud

Organization settings
  • Name
  • Plan
  • Billing & payment info

Stored in Superblocks Cloud servers

Same as Superblocks Cloud

RBAC & Governance
  • Roles & permissions
  • Role assignments
  • Base permission settings

Stored in Superblocks Cloud servers

Authorization checks are performed by Superblocks Cloud servers.

For deployed code, authorization is performed by Global Edge Network nodes when fetching UI/API code before rendering/executing.

Same as Superblocks Cloud

Application UI
  • Pages & Layouts
  • UI Components
  • State, events, timers
  • Frontend JavaScript

Stored in Superblocks Cloud servers and can sync with Git repo using Source Control

Users' browser fetches and renders UI from Cloud server Global Edge Network

Same as Superblocks Cloud

Backend Code

Stored in Superblocks Cloud servers and can sync with Git repo using Source Control

Agents fetch code from Cloud server or Global Edge Network to execute code.

Same as Superblocks Cloud, PLUS

Agents poll Superblocks Cloud server for Schedule Job cron schedules

Integrations
  • Shared configuration
  • Connection credentials

Stored in Superblocks Cloud server

Credentials can be stored in Secret Manager or Cloud server

When APIs execute, agents fetch Integration info either from Cloud servers or Global Edge Network

Same as Superblocks Cloud, PLUS

Credentials can be stored on the agent and accessed via OPA Environment Variables

On-Premise agent resolves all bindings and connects directly to data sources.

Telemetry & Audit Logs
  • Application view logs
  • API & step execution events
  • print()/console.log() statements
  • Log of user actions in platform (e.g. user login)

Execution logs are generated by the agent and sent to Superblocks Cloud

System logs are generated by Superblocks Cloud when users take action in the browser

Logs can be sinked to 3rd party monitoring solutions like Datadog, New Relic, SumoLogic, and more.

Same as Superblocks Cloud

Usage & Billing
  • # of API calls
  • # of page views
  • # & type of Integrations used
  • User activity

API & step executions are sent from agents to Superblocks Cloud services

Product usage is tracked by Superblocks Cloud

Same as Superblocks Cloud

For a full list of the outbound network calls the agent makes along with request/response see the Github page here.

Additional resources

Learn more about the On-Premise Agent here: