Name: managing-stacks
Author: celigo

Configure Celigo stacks -- pointers to your own compute environment (a self-hosted `server` or an AWS `lambda`) where Celigo runs extension code (script hooks and connector wrappers) instead of on its hosted JavaScript runtime. A stack stores the address and credentials of that runtime, not the code

<! TIER:1 Managing Stacks A stack is a pointer to your own compute environment where Celigo runs extension code the script hooks and connector wrappers that would otherwise run on Celigo's hosted JavaScript runtime. A stack holds the address and credentials of that environment, not the logic. At runtime, when a hook or wrapper is configured to use a stack, Celigo dispatches that function's execution to the stack instead of running it on its own managed runtime. Concerns when managing stacks: Necessity most accounts never need a stack; the hosted runtime handles the vast majority of extension logic. A stack is for a real trigger (see the decision matrix). Type and config server (a self hosted HTTP endpoint) or lambda (an AWS Lambda function), each with its own config block. Credentials a server carries an auto generated systemToken ; a lambda carries AWS keys. Both are masked in responses and demand credential discipline. References a stack does nothing on its own. It matters only once a hook (via stackId on an export/import) or a wrapper connection (via wrapper. stackId ) points at it. Stacks are a resource type in their own right. They are referenced by script hooks and by wrapper connections. No tool on the Celigo Platform MCP server reads or changes a stack or its token, so manage them with the CLI, the REST API ( /v1/stacks ) or the UI; over MCP, a hook's stackId on its export or import and a wrapper connection's wrapper. stackId still show which stack they use. The Stack Is the Runtime, Not the Code The distinction the whole domain hangs on: The code is the logic: a hook (a JavaScript function on an export/import preMap , postSubmit , etc.) or a connector wrapper (the server side JavaScript that implements a custom adaptor). With a stack, that code lives on your server or Lambda, not in a Celigo script. The stack is where that code runs . A hook names either a script ( scriptId , run on Celigo's runtime) or a stack ( stackId ), together with the function to call for a stack, a function your deployed extension exposes. A wrapper connection names its stack in wrapper. stackId , and its logic runs from the code deployed there. So moving a hook onto a stack means deploying its function to the stack's runtime, then, in one update, replacing scriptId with stackId and setting function to the name the deployed code exposes (often not the script's function name). The API doesn't enforce the either/or: a hook saved with both ids answers 200 and keeps both, and then the script and the stack each list the step as a dependent, leaving it unclear which runs. After the move, changing what the hook does is a deployment to your server or Lambda, not script work. A stack is bring your own compute : it supplies the environment, not the behavior. Stack vs On Premise Agent Both put "your own infrastructure" in the loop, but for opposite reasons keep the boundary straight: A stack is about compute running your extension code (hooks/wrappers) on your server or Lambda. An on premise agent is about connectivity a tunnel that lets Celigo reach private apps or networks behind your firewall (a database or app with no public endpoint). "Run our code" stack. "Reach our private system" on premise agent. A single flow can use both: an agent to reach a private database, and a stack to run a custom hook. Quick Reference Do You Need a Stack? Default: no. Celigo's hosted JavaScript runtime runs hooks out of the box. Reach for a stack only on a real trigger: Situation Need a stack? A hook to transform, filter, or enrich records No the hosted runtime handles it Code that needs libraries, native dependencies, more memory, or longer execution than the sandbox allows Yes Compliance/security requirement that extension code and the data it touches never leave your environment Yes A custom connector implemented as a wrapper connection Yes a wrapper runs on a stack you operate Installing a template, or cloning resources, whose preview says stackRequired: true (a hook or wrapper connection that runs on a stack) Yes the Marketplace installer asks which stack to use; an API install or clone takes it as stackId and fails with 400 stack not found without it, and every stack reference in the copy points at that one stack. celigo templates install <id passes stackId in the body you pipe; the CLI's clone commands don't send one ([using marketplace templates](../using marketplace templates/SKILL.md)) Reaching a private database or app behind a firewall No that's an on premise agent, not a stack server vs lambda Neither is "better" it's a fit question based on where the team already runs infrastructure. server lambda What it is A self hosted, always on HTTP endpoint you run and patch A serverless AWS Lambda function Celigo invokes Scaling / uptime You own it AWS manages it Access control The system token (step 5) and your own firewall; ipRanges is deprecated AWS IAM Trade offs Full control, no cloud provider coupling Pay per invocation, but AWS coupling and cold starts Leans toward Teams with an existing managed server or non AWS environment Teams already deep in AWS Minimum Required Fields Every stack needs name and type . framework is twoDotZero (the only supported version). The rest depends on type : Type Config block Required fields server server hostURI (the reachable HTTP(S) endpoint Celigo calls). systemToken is auto generated you do not set it. Don't rely on ipRanges : it's deprecated, and the platform stores whatever it's sent without checking it. lambda lambda accessKeyId , secretAccessKey , awsRegion , functionName . Optional language ( Node.js default, or C / Java / Other ). awsRegion is an enum (e.g. us east 1 , us west 2 , eu west 1 , eu central 1 , ap southeast 1 , ...). functionName accepts a Lambda function name or full ARN. Both secrets ( systemToken , secretAccessKey ) are masked as in responses; an update sends them back that way (Gotcha 5). Referencing a Stack ( stackId ) A stack is inert until something points at it: Hooks an export/import hook definition names the stack with stackId instead of scriptId , plus the function your deployed extension exposes. Send one or the other: a hook sent with both keeps both. Wrapper connections a wrapper connection names the stack whose server side JavaScript implements it in wrapper. stackId , inside the wrapper block, next to wrapper.pingFunction : the function on the stack that Celigo calls to test the connection. The connection form requires the stack for a standalone wrapper; an Integration App's wrapper connections ( connectorId set) omit it and take the ping function from the app. To confirm what actually runs on a stack, list its dependents ( celigo stacks dependencies <id ) the hooks and wrapper connections pointing at it. Related Skills [configuring connections Connection Types](../configuring connections/SKILL.md connection types) wrapper connections whose custom connector code runs on a stack referenced by wrapper. stackId [writing scripts How to Write a Script](../writing scripts/SKILL.md how to write a script) hooks that run as Celigo scripts; a hook on a stack names stackId instead of scriptId [managing on premise agents](../managing on premise agents/SKILL.md) the connectivity counterpart: a stack runs your code , an on premise agent reaches your private systems [getting started Core Concepts](../getting started/SKILL.md core concepts) where stacks fit among the core resource types <! TIER:2 How to Manage a Stack 1. Confirm you actually need one Use the [Do You Need a Stack?]( do you need a stack) matrix. When a user asks "should I set up a stack for this hook," the honest first answer is usually "probably not the managed runtime handles it," then escalate only if heavier/specialized code, a compliance requirement, or a custom connector wrapper is genuinely in play. If the real need is reaching a private system, that's an on premise agent, not a stack. 2. Choose the type Use the [server vs lambda]( server vs lambda) matrix. Pick by where the team already runs infrastructure and how they want to operate it. 3. Check for existing stacks Before creating a new one, look for a stack you can reuse: celigo stacks list also shows stacks other users have shared with you ( shared: true ). Sharing one goes through the API: POST /v1/stacks/{ id}/invite with the user's email creates a pending share they must accept. No CLI command or MCP tool shares a stack, and a stack behind an Integration App can't be shared. 4. Create the stack Data blocks differ by type . Create the metadata; the runtime code is deployed and owned separately. Example lambda stack.json (use a placeholder here and supply the real key only in a local file or the UI): 5. Wire up authentication server the systemToken is generated on creation. Retrieve the unmasked value from the UI (the stack's "Show token" action) or with celigo stacks token <id , then set it as the INTEGRATOR EXTENSION SYSTEM TOKEN environment variable on every server that runs the extension code. To rotate it, run celigo stacks rotate token <id (the old token is invalidated immediately) and re fetch the new one. Both commands print or replace a secret, so have the user run them where the value goes straight into the server's environment, not into a chat. lambda the AWS IAM user behind accessKeyId / secretAccessKey must have the lambda:InvokeFunction permission for the target function, and awsRegion must match where the function is deployed. 6. Point a hook or wrapper at the stack The stack only runs code once referenced: Hook deploy the hook function to the stack's runtime, then set stackId on the hook definition on the export/import in place of scriptId , with function naming the deployed function. A hook can't be patched on its own, so this is a full update of the export or import: read it, change only the hook (remove scriptId , add stackId , set function ), and write the whole document back. Leave the script itself alone unless the user asks; other steps may still use it. See [writing scripts How to Write a Script](../writing scripts/SKILL.md how to write a script) for hook wiring. Wrapper connection set wrapper. stackId on the wrapper connection, and wrapper.pingFunction to the function your extension exposes for the connection test (Test Connection, or celigo connections ping <id , calls it). See [configuring connections Connection Types](../configuring connections/SKILL.md connection types). 7. Verify Confirm the expected hooks and wrapper connections reference the stack before relying on it: CLI Commands celigo stacks token and rotate token call GET and DELETE /v1/stacks/{id}/systemToken ; the UI's "Show token" action is the alternative. <! TIER:3 Pre Submit Checklist [ ] Confirmed a stack is genuinely needed (heavier/specialized code, compliance, or a custom connector wrapper) not a routine hook the hosted runtime could handle. [ ] Correct type chosen ( server vs lambda ) based on where the team operates infrastructure. [ ] framework set to twoDotZero . [ ] server : hostURI is reachable over HTTPS; a firewall in front of it allows Celigo's published addresses ([configuring connections Partner IP allow lists](../configuring connections/SKILL.md partner ip allow lists)), not the deprecated ipRanges . [ ] server : systemToken retrieved (not set) and configured as INTEGRATOR EXTENSION SYSTEM TOKEN on the runtime. [ ] lambda : awsRegion , f