Look up any CoDesign term in plain words, with the CE.SDK name it maps to in code.
Agent Runner#
The agent runner is the part of your backend that talks to the model. It runs
the agent loop: it sends a model a task and a list of tools, runs
the tool calls the model asks for, and sends back the results until the model
is done. It gets the tools from prepareCoDesign in @imgly/codesign-sdk.
It runs on your server or in a background job, holds your model credential (see Credentials) and your design store, and is the only part that calls the model. It never runs an engine itself; that is the executor’s job.
AI Gateway#
IMG.LY’s AI gateway, at https://gateway.img.ly/v1, serves AI models to your
agent runner through OpenAI’s Chat Completions API, so any agent framework that
can call that API can use it. It takes your CoDesign license key as its API
key, and its calls are charged to your IMG.LY account, so you need no account
with a model provider.
With prepareCoDesign({ gateway }), the agent can also generate images, video,
speech, music, and sound effects through it.
Asset#
An asset is something a design can use: a photo, a logo, a typeface, a color,
or a template. CE.SDK describes each with its Asset type, which carries an
id and, under meta.uri, the address the engine fetches.
Assets live in your own storage. An asset source is a searchable catalog of
them in CE.SDK’s format, one per collection, registered by a plugin.
A source says which kinds of file it holds by MIME type
(Multipurpose Internet Mail Extensions type), the standard label such as
image/png, and that decides what the agent does with it: a source of
typefaces is where it looks up fonts, a source of images is where it searches
for pictures and may keep new ones.
Conversation#
A conversation is your id for one chat, one job, or one request: the work one
set of tools does, passed as prepareCoDesign({ conversation }). All its
designs open on one executor, with the plugins its runner sends, and that
executor never serves another conversation. A one-off run is one
conversation.
Credentials#
| Credential | What it does | Where it lives |
|---|---|---|
| Your CoDesign license key | Belongs to your IMG.LY account. Pays for exports, AI models, and generation. | Your servers and the executor image’s environment. Never a page. |
| A grant (Grant) | Starts an engine. Charges nothing. | The executor. |
The executor token (EXECUTOR_TOKEN) |
Lets your runner, and nobody else, call an executor container. | Your runner and the container’s environment. |
A short-lived credential, such as the grant or a token you give a plugin, may sit where the model’s code can read it; a key, such as your CoDesign license key, never may ( Where Keys Live).
Design#
A design is one CE.SDK scene your product keeps, named by a design id of yours. A scene is a text document that describes every page, text, image, and shape; each of those elements is a block. A design is saved in one of two forms:
- A scene string, which references its images and fonts by address.
- An
.imglyarchive, the scene packed with its images and fonts, so it opens anywhere.
Every design has a version, a value that changes on every save, such as your table’s revision number. An edit names the version it builds on and is refused when that version is no longer current, so the agent never builds on a design it has not seen ( Concurrent Edits).
Executor#
The executor is where one CE.SDK engine runs, and where the JavaScript the
model writes runs against it. The engine is CE.SDK, IMG.LY’s design engine,
without its editor’s screen. The executor also charges every exported file to
your IMG.LY account ( Billing). It is
IMG.LY’s Docker image, imgly/codesign-executor on Docker Hub, which you run
unchanged as a container on your infrastructure, apart from your runner, your
keys, and your database ( Security).
Each executor serves one conversation and never another. Your
acquire function, which you pass to remoteExecutors, answers the address of
a conversation’s executor.
Grant#
A grant is a CE.SDK license that IMG.LY’s /activate endpoint
(https://api.img.ly/activate) issues for your CoDesign license key. It names
your license without containing the key. It lets the engine start but charges
nothing. It lasts at most 24 hours, and an engine checks it only when it
starts. The executor fetches its own grant when its container starts.
Metering#
Metering is IMG.LY’s billing service, at https://api.img.ly. The executor
charges each exported file through it with your license key, once per
render ID. What is charged is listed under Billing in
Host the Executor.
Plugin#
A plugin is CE.SDK’s unit for adding something to an engine: a JavaScript file
whose default export takes options and returns a CE.SDK EnginePlugin.
Yours registers your asset sources and, when your addresses are not
plain https links, tells the engine how to fetch them.
You list it in prepareCoDesign({ plugins }) as { module, options }, the
file’s text and this person’s values, and the runner sends both to the
executor when it opens a design. Your browser editor applies the same file.
IMG.LY’s own catalogs come as plugins too: googleFonts(), cesdkDefaults(),
and cesdkDemo() ( Bring Your Brand).
Render ID#
The render id names one export: a hash of the design, its version, its content, the file format, and the export options. Metering charges a render id once, so an export that is retried, by your code or by the model, is charged once. A preview is a small render the model looks at; it has no render id and is never charged.
Session#
An engine session, or session for short, is one design of a conversation
open in the executor’s engine. It is only a cache: the design is always in
your store, and a session that is gone is loaded again from there. A design’s
engine session ends 3 minutes after its last call, or when your runner calls
codesign.release() ( Host the Executor).
Store#
Your design store is two functions over the table where your product keeps
designs, passed as prepareCoDesign({ designs }). They run in your agent
runner, never on the executor. read returns a design’s content, its
version, and the CE.SDK version that saved it; write stores new content
only while the design is still at the version the call read. Without a store,
designs live in memory for one run
( Connect Your Storage).
Tenant#
A tenant is one of your customers, with its own designs, assets, and brand. The SDK has no tenants of its own: you keep tenants apart by giving each conversation that tenant’s design store and plugins ( Sign-In and Tenant Identity).
Tool#
A tool is a function the model may call, described to it by a name, a
sentence, and a JSON schema for its arguments. codesign.tools are the design
tools; you can add tools of your own ( Tools).
Turn#
A turn is the tool calls the model makes in answer to one message, until it answers in text. Turns belong to your agent loop; the SDK sees only tool calls.
Next Steps#
- Architecture — see how these parts work together in one request.
- Tools — see what the tools let the agent do.
- API Reference — look up each option and type this glossary names.
- Security — see where each credential may sit and why.