# About Source: https://docs.coralos.ai/about Kubernetes for AI agents: CoralOS is a platform for everything between your agents and production: registry, runtimes, security, and orchestration. ### Value for Developers CoralOS allows agents to be reused across the internet, It allows agent developers to publish agents to the global marketplace where they can be used on demand by anyone. * [**Agent developers**](https://docs.coralos.ai/guides/writing-agents) earn incentives when their agents are used. * [**Application developers**](/guides/integrating-with-your-app) can mix and match from Coral's growing [library](https://github.com/Coral-Protocol/awesome-composable-agents) of agents to assemble advanced systems faster and without vendor lock-in. ### Key Components Add any agent from any framework to our marketplace in minutes. Discover, publish, monetize & verify agents with built-in attestation. Orchestrate many agents together easily. Monitor, test & debug agents during development. Turn any MCP server into a coralized agent. ### Key Benefits Agent communication is scoped to sessions. Applications remain responsible for authenticating users, controlling access to the server API, and mapping callbacks and stored results to the correct tenant. Leverage agents from any framework and integrate pre-built, specialized agents developed by others. Instead of reinventing the wheel, plug them directly into your system for faster deployment. Most multi-agent systems are built hierarchically, where a central “planner” delegates tasks to worker agents or runs workflows sequentially. This structure quickly becomes a bottleneck, where one agent has too much responsibility. Dio5 Pn  Coral’s architecture introduces a **graph-based design** that enables **direct agent-to-agent communication**, unlocking significant improvements in performance, scalability, and cost-efficiency. Instead of funneling decisions through a single controller, agents can coordinate dynamically and share progress in real time. As shown in[*Anemoi: A Semi-Centralized Multi-Agent System Based on Agent-to-Agent Communication*](https://arxiv.org/abs/2508.17068) (Ren et al., 2025), this approach: > “Enables structured and direct inter-agent collaboration, allowing all agents to monitor progress, assess results, identify bottlenecks, and propose refinements in real time.” > > “Reduces reliance on a single planner, supports adaptive plan updates, and minimizes redundant context passing, resulting in more scalable and cost-efficient execution.” This architecture has also demonstrated measurable performance gains on benchmarks: > “On the GAIA benchmark, Anemoi achieved 52.73 % accuracy with a small LLM (GPT-4.1-mini) as the planner, surpassing the strongest open-source baseline OWL (43.63 %) by +9.09 % under identical LLM settings.” Because each agent in Coral’s architecture handles smaller, well-defined responsibilities and communicates via a scalable graph, you gain: * **Higher throughput** — Multiple agents run concurrently without blocking, using the server’s coroutine-based connection handling. Blocking agents made in e.g. Python do not impact the whole system, as they would be isolated processes. * **Improved reasoning quality** — Specialized agents continuously refine each other’s outputs in real time. * **Safer and more predictable AI systems** — Instead of just scaling performance by making models larger, Coral lets you scale by adding more intelligent agents. See more results on the **GAIA benchmark:** [https://gaia.coralos.ai/](https://gaia.coralprotocol.org/) ### Ready to Start Building? For MCP-to-agent conversion, we now recommend a coding agent such as Codex or Claude Code, using the Koog agent template as a reference. Coralizer's `link` command is still useful for making local agents available to your server. Run Coral Server and create your first agent session. # Submit an agent claim Source: https://docs.coralos.ai/api-reference/agent-rpc/submit-an-agent-claim /api_v1.json post /api/v1/agent-rpc/claim Submits a claim for work performed # Close an active session Source: https://docs.coralos.ai/api-reference/local/close-an-active-session /api_v1.json delete /api/v1/local/session/{namespace}/{sessionId} Closes an active session, cancelling all running agents # Create namespace Source: https://docs.coralos.ai/api-reference/local/create-namespace /api_v1.json post /api/v1/local/namespace Creates a new empty namespace # Create session Source: https://docs.coralos.ai/api-reference/local/create-session /api_v1.json post /api/v1/local/session Creates a new session in a given namespace # Delete a namespace Source: https://docs.coralos.ai/api-reference/local/delete-a-namespace /api_v1.json delete /api/v1/local/namespace/{namespace} Deletes a given namespace, closing any session that it may contain # Executes a session Source: https://docs.coralos.ai/api-reference/local/executes-a-session /api_v1.json post /api/v1/local/session/{namespace}/{sessionId} Executes a session was created with deferred execution # Get base session state Source: https://docs.coralos.ai/api-reference/local/get-base-session-state /api_v1.json get /api/v1/local/session/{namespace}/{sessionId} Returns a session's state # Get extended session state Source: https://docs.coralos.ai/api-reference/local/get-extended-session-state /api_v1.json get /api/v1/local/session/{namespace}/{sessionId}/extended Returns a session's extended state # List base namespace states Source: https://docs.coralos.ai/api-reference/local/list-base-namespace-states /api_v1.json get /api/v1/local/namespace Returns a list of namespace states # List base session states Source: https://docs.coralos.ai/api-reference/local/list-base-session-states /api_v1.json get /api/v1/local/namespace/{namespace} List base session states for a given namespace # List extended namespace states Source: https://docs.coralos.ai/api-reference/local/list-extended-namespace-states /api_v1.json get /api/v1/local/namespace/extended Returns a list of extended namespace states # List extended session states Source: https://docs.coralos.ai/api-reference/local/list-extended-session-states /api_v1.json get /api/v1/local/namespace/{namespace}/extended List extended session states for a given namespace # AgentGraphRequest Source: https://docs.coralos.ai/api-reference/models/AgentGraphRequest # GraphAgentRequest Source: https://docs.coralos.ai/api-reference/models/GraphAgentRequest # GraphAgentTool Source: https://docs.coralos.ai/api-reference/models/GraphAgentTool # SessionRequest Source: https://docs.coralos.ai/api-reference/models/SessionRequest # SessionRuntimeSettings Source: https://docs.coralos.ai/api-reference/models/SessionRuntimeSettings # Add thread participant Source: https://docs.coralos.ai/api-reference/puppet/add-thread-participant /api_v1.json post /api/v1/puppet/{namespace}/{sessionId}/{agentName}/thread/participant Adds an agent to a thread masquerading as the specified agent # Close thread Source: https://docs.coralos.ai/api-reference/puppet/close-thread /api_v1.json delete /api/v1/puppet/{namespace}/{sessionId}/{agentName}/thread Closes a thread masquerading as the specified agent # Create thread Source: https://docs.coralos.ai/api-reference/puppet/create-thread /api_v1.json post /api/v1/puppet/{namespace}/{sessionId}/{agentName}/thread Creates a new thread masquerading as the specified agent # End agent runtime Source: https://docs.coralos.ai/api-reference/puppet/end-agent-runtime /api_v1.json delete /api/v1/puppet/{namespace}/{sessionId}/{agentName} Forcefully cause an agent to exit it's own runtime # Remove thread participant Source: https://docs.coralos.ai/api-reference/puppet/remove-thread-participant /api_v1.json delete /api/v1/puppet/{namespace}/{sessionId}/{agentName}/thread/participant Removes an agent from a thread masquerading as the specified agent # Send message Source: https://docs.coralos.ai/api-reference/puppet/send-message /api_v1.json post /api/v1/puppet/{namespace}/{sessionId}/{agentName}/thread/message Sends a message in a thread masquerading as the specified agent # Get registry agents Source: https://docs.coralos.ai/api-reference/registry/get-registry-agents /api_v1.json get /api/v1/registry Returns a list of all agents available in this servers registry # Inspect linked server registry agent Source: https://docs.coralos.ai/api-reference/registry/inspect-linked-server-registry-agent /api_v1.json get /api/v1/registry/linked/{linkedServerName}/{agentName}/{agentVersion} Returns all details about a specific agent from a specific linked server # Inspect local registry agent Source: https://docs.coralos.ai/api-reference/registry/inspect-local-registry-agent /api_v1.json get /api/v1/registry/local/{agentName}/{agentVersion} Returns all details about a specific agent in the local registry # Inspect marketplace registry agent Source: https://docs.coralos.ai/api-reference/registry/inspect-marketplace-registry-agent /api_v1.json get /api/v1/registry/marketplace/{agentName}/{agentVersion} Returns all details about a specific agent in the marketplace # Privacy Policy Source: https://docs.coralos.ai/cloud/privacy Coral Cloud's privacy policy Last updated: 03 Feb 2026 At CoralOS, Inc. (“Coral”, “we”, “us”, or “our”), we are committed to protecting your personal information and your right to privacy. We want you to be fully informed about the information we collect, how it is used, shared, and protected, and the choices you have with it and explain the privacy and data practices at Coral. This privacy policy (the "Policy") applies to all information collected through our website [https://coralcloud.ai/](https://coralcloud.ai/) (the "Website") and any related services, sales, marketing or events (referred collectively to as "Services"). If there are any terms in this Policy that you do not agree with, you should immediately discontinue the use of our Services. If you have questions or concerns about our practices in regards to your personal information, please contact us at [cloudprivacy@coralos.ai](mailto:cloudprivacy@coralos.ai) and we'll get back to you as soon as we can. # When we collect personal information We collect personal information when: * You sign up for our Services. * You visit or interact with our services, including by interacting with Agents, creating Sessions, API keys, or by sending it through the console or a connected application. * You add your email address to a separate waiting list * You engage with our support team or otherwise communicate with us. * You view or interact with our emails or other communications Contact address for privacy matters: [cloudprivacy@coralos.ai](mailto:cloudprivacy@coralos.ai) # Types of personal information we collect We collect the following categories of personal information: * Information you provide directly to us * Information when you register for an account, including if you sign in using Google credentials * Information from your interactions with our support team or inquiries into our Services, which may include providing us with your name, work or personal email, phone number, discord username or other social media link and time zone. * Our Website allows you to purchase our Services, including providing us with your credit card and billing information # How we use collected personal information We use the personal information that you give and we collect for the following purposes: * To provide our Services, including providing AI services. * For customer support by responding to your issue reports, questions or feedback. * To improve or troubleshoot any issues with our Services. * To communicate with you, such as sending you email or SMS updates about new features, products, and services. * To comply with our agreements or policies. * For other business and legal purposes, such as to detect and prevent fraud, to collect amounts owing to us, and to maintain business records. # How we may disclose your information We may disclose your information with your consent. We may also share your information with our corporate affiliates, as well as vendors or service providers who: * Process credit card or other payments and enable subscription Services. * Help us communicate with you. * Manage and optimize our Website and Services. * To measure website analytics, use of our applications, and to synchronize content with select third party websites or services. # Your rights and how to exercise them * Access the personal information we maintain about you. * Delete the personal information we maintain about you, unless such information is necessary for compliance with our legal or regulatory obligations. * Correct inaccurate personal information we maintain about you. * Opt-Out of certain uses of your personal information. You can opt out of: * Email marketing: you may unsubscribe to our commercial email list by following the instructions provided in the email. You can exercise these rights by contacting [cloudprivacy@coralos.ai](mailto:cloudprivacy@coralos.ai) # Terms of Service Source: https://docs.coralos.ai/cloud/tos Last Update: 04 Feb 2026 Welcome to Coral Cloud! These Terms of Service are a legally binding agreement between CoralOS, Inc. (“Coral”,“we”, or “our” as applicable) and you (“Customer”, “you” or “your” as applicable). Any mention of “you” or “Customer” in these Terms shall either mean you, the end user in your personal capacity who is utilizing the Services (as defined), or in case you are acting as a duly authorized Representative (as defined) of an entity, the reference shall mean such entity. “Party” means Coral or Customer, as applicable, and “Parties” means Coral and Customer collectively. By accessing or using the Services, you represent and warrant that: (a) you are at least 18 years of age or over the age of majority in the jurisdiction where you are a resident or citizen; and (b) your registration and your use of the Service is in compliance with any and all applicable laws and regulations. If an end user is under 18, you as a parent consent to their such use of the Services, and you take on the liability as if you were the end user. PLEASE READ THESE TERMS CAREFULLY AS THEY ARE A LEGAL BINDING CONTRACT BETWEEN THE PARTIES: BY CLICKING “I ACCEPT”, OR BY DOWNLOADING, INSTALLING, OR OTHERWISE ACCESSING OR USING THE SERVICE, YOU AGREE THAT YOU HAVE READ AND UNDERSTOOD, AND, AS A CONDITION TO YOUR USE OF THE SERVICE, YOU AGREE TO BE BOUND BY, THE FOLLOWING TERMS AND CONDITIONS, INCLUDING CORAL’S PRIVACY POLICY, ACCEPTABLE USE POLICY, AND COMMUNITY GUIDELINES (TOGETHER, THESE “TERMS”). IF YOU ARE NOT ELIGIBLE, OR DO NOT AGREE TO THE TERMS, THEN YOU DO NOT HAVE OUR PERMISSION TO USE THE SERVICE. THESE TERMS CONTAIN CERTAIN DISCLAIMERS LIMITING CORAL LIABILITY. In addition to these Terms, please review our Privacy Policy which forms part of the terms and conditions which apply to you by reference – it states how we access and use your information. 1. DEFINITIONS. “Acceptable Use Policy” means Coral’s standard acceptable use policy, currently available at [https://coralcloud.ai/acceptable-use-policy](https://coralcloud.ai/acceptable-use-policy). “Action” means any claim, action, cause of action, demand, lawsuit, inquiry, audit, notice of violation, proceeding, litigation, citation, summons, subpoena, or investigation of any nature, civil, criminal, administrative, regulatory, or other, whether at law, in equity, or otherwise. “Agent” means an autonomous or semi-autonomous software entity that can perform tasks, process information, and interact with other Services or third-party resources, which may be powered by one or more Models. “Affiliate” of a Party means any other party that directly or indirectly, through one or more intermediaries, controls, is controlled by, or is under common control with, such Party. The term “control” (including the terms “controlled by” and “under common control with”) means the direct or indirect power to direct or cause the direction of the management and policies of a Person, whether through the ownership of voting securities, by contract, or otherwise. “Authorized User” means each person authorized by Customer to use the Services. “Content” means commands, code, Models, text, data, articles, images, photographs, graphics, software, applications, packages, designs, features, and other digital materials. “Customer Data” means Customer Inputs and Outputs. For the avoidance of doubt, Customer Data does not include Resultant Data or any other information reflecting the access or use of the Services by or on behalf of Customer. “Community Guidelines” means Coral’s standard community guidelines, currently available at [https://coralcloud.ai/community-guidelines](https://coralcloud.ai/community-guidelines). “Documentation” means any manuals, instructions, or other documents or materials that Coral provides or makes available to Customer in any form or medium and which describe the functionality, components, features, or requirements of the Services, including any aspect of the operation, use, or support thereof. “Fees” means the amounts Customer is obligated to pay Coral in connection with use of its Services. “Harmful Code” means any software, hardware, or other technology, device, or means, including any virus, worm, malware, or other malicious computer code, the purpose or effect of which is to (a) permit unauthorized access to, or to destroy, disrupt, disable, distort, or otherwise harm or impede in any manner any (i) computer, software, firmware, hardware, system, or network; or (ii) any application or function of any of the foregoing or the security, integrity, confidentiality, or use of any data processed thereby; or (b) prevent Customer from accessing or using the Services as intended by these Terms. “Inputs” means Content that is uploaded to be processed through the Services. “Intellectual Property Rights” means patents, patent applications, inventions, and discoveries (whether patentable or unpatentable), copyrights and copyrightable works, moral rights, trademarks, service marks, trade names, domain name rights, know-how and other trade secret rights, rights in software, databases, artificial intelligence and AI algorithms, and all other intellectual property rights and similar forms of protection throughout the world. “Law” means any statute, law, ordinance, regulation, rule, code, order, constitution, treaty, common law, judgment, decree, or other requirement of any federal, state, local, or foreign government or political subdivision thereof, or any arbitrator, court, or tribunal of competent jurisdiction. “Login Credentials” means any user-name, identification number, password, license or security key, security token, PIN, or other security code, method, technology, or device, used alone or in combination, to verify Customer or an Authorized User’s identity and authorization to access and use the Services. “Losses” means any and all losses, damages, deficiencies, claims, actions, judgments, settlements, interest, awards, penalties, fines, costs, or expenses of whatever kind, including reasonable attorneys' fees and the costs of enforcing any right to indemnification hereunder and the cost of pursuing any insurance providers. “Model” means a trained, packaged, and published software program that accepts Inputs and returns Outputs. “Output” means the Content generated by the Services based on Customer’s Inputs. “Privacy Policy” means Coral’s Privacy Policy which sets out Coral’s approach to use and protection of data obtained through the Services. “Resultant Data” means data and information related to Customer's use of the Services that is aggregated and anonymized, including to compile statistical and performance information related to the provision and operation of the Services. “Representatives” means employees, officers, directors, consultants, agents, or independent contractors. “Services” means the hosted software platform provided on a SaaS basis giving Customers ability, for the applicable Fee, to run Models and Agents in the cloud using Coral Cloud API or Coral’s Website interface. “Session” means a discrete period of time or a specific instance of interaction with an Agent through the Services. “Website” means, in respect of Coral, [www.coralcloud.ai](http://www.coralcloud.ai) and all its subdomains. 2. SERVICES 2.1 Use Rights. Coral hereby grants Customer a non-exclusive, non-transferable, revocable, non-sublicensable right to access and use the Services and Documentation solely for use in accordance with the terms and conditions set out in these Terms and on our Website. The Services are only available to Customers who can form legally binding contracts under Law. You are not eligible to be a Customer either directly or indirectly if you are barred from using the Services under the Laws of the United States or any other applicable jurisdiction, including pursuant to Section 12.7 (Compliance with Laws and Export Regulations) in these Terms. 2.2 Features and Benefits. (a) Among other benefits of our Services, you can access and run Agents and Models which are either private (proprietary to Customer or Coral) or public open-sourced Models as further set out on the Website (see our disclaimers in Section 8 regarding Models and Agents). You can build and publish custom Models from scratch. For more information on how Models and Agents are built on Coral, what tools we use, how you can deploy them and other useful information for your use of our Services, please refer to our Website. (b) In addition to using the Models and Agents, Customers can obtain more control over how they run a Model by allowing deployments of a Model (“Deployments”) on the Services which allow Customer to: roll out new versions of a Model without having to edit code; auto-scale Models to handle extra load and scale to zero when Models are not being used, saving cost; keep instances always on to avoid cold boots; customize what hardware the Models runs on; monitor whether instances are setting up, idle, or processing predictions; monitor the predictions that are flowing through the Model; and also limit the maximum number of instances the Deployment can use to limit Customer’s maximum spend, or set a minimum to keep some instances warm and ready for predictions. (c) As of the date of these Terms, all Agents available on Coral Cloud are developed by Coral. We may in the future allow user-provided Agents on the Services. User-provided Agents will be clearly denoted as such. Coral accepts no responsibility or liability for the behavior, accuracy, or any outcomes resulting from the use of user-provided Agents. (d) While Coral Cloud generally does not offer free Agents, users may be granted free credits at Coral's discretion to use the Services. Abuse of free credits, including but not limited to the creation of multiple accounts by the same individual or entity to obtain additional credits, is strictly prohibited and may lead to immediate termination of all associated Accounts. See Section 4 for clauses related to fees. (e) Our Website Documentation includes guidance documents and weekly bulletins that are available on our Website subject to the rights granted under these Terms or as explicitly set out on the Website. We grant you a non-transferable, revocable, fully paid up license to use the foregoing solely for your and your Representatives’ non-commercial purposes. 2.3 Account Set-Up. (a) To use our Services, you must sign on to Coral using your account (“Account”) using your applicable login credentials. (b) You are responsible for maintaining the confidentiality of your Account and Login Credentials, including but not limited to the restriction of access to your computer and/or Account. You are responsible for any and all activities or actions that occur under your Account and/or Login Credentials, whether your password is with our Service or a third-party service. You must notify us immediately at [support@coralcloud.ai](mailto:support@coralcloud.ai) upon becoming aware of any actual or potential breach of security or unauthorized use of your Account or Login Credentials. You may not use as a username the name of another person or entity or that is not lawfully available for use, a name or trademark that is subject to any rights of another person or entity other than you, without appropriate authorization. You may not use as a username any name that is offensive, vulgar or obscene, subject to our discretion. (c) Coral may suspend, terminate, or otherwise deny Customer's or any Authorized User's access to or use of all or any part of the Services, without incurring any resulting obligation or liability, if: (a) Coral receives a judicial or other governmental demand or order, subpoena, or law enforcement request that expressly or by reasonable implication requires Coral to do so; or (b) Coral believes, in its discretion, that: (i) Customer has failed to comply with any material term of these Terms, or accessed or used the Services beyond the scope of the rights granted or for a purpose not authorized under these Terms or in any manner that does not comply with any Documentation; or (ii) Customer is, has been, or is likely to be involved in any fraudulent, misleading, or unlawful activities relating to or in connection with any of the Services. This Section 2.3 does not limit any of Coral's other rights or remedies, whether at Law, in equity, or under these Terms. 2.4 Subscriptions Some parts of the Services are billed on a subscription basis with automatically recurring payments for periodic charges (“Subscriptions”). The “Subscription Billing Date” is the date when you purchase your first Subscription to the Services. The Subscription will begin on the Subscription Billing Date and continue for the subscription period that you select on your Account (such period, the “Initial Subscription Period”), and will automatically renew for successive periods of the same duration as the Initial Subscription Period (the Initial Subscription Period and each such renewal period, each a “Subscription Period”) unless you cancel the Subscription or we terminate it. If you activate a Subscription, then you authorize Coral to periodically charge, on a going-forward basis and until cancellation of the Subscription, all accrued sums on or before the payment due date. Your account will be charged automatically on the Subscription Billing Date and thereafter on the renewal date of your Subscription for all applicable fees and taxes for the next Subscription Period. You must cancel your Subscription before it renews in order to avoid billing of the next periodic Subscription Period to your account. Coral or its third-party payment processor will bill the periodic Subscription fee to the payment method associated with your Account or that you otherwise provide to us. You may cancel the Subscription by contacting us at [support@coralcloud.ai](mailto:support@coralcloud.ai). Your cancellation must be received before the renewal date in order to avoid charge for the next subscription period. 2.5 No Guarantees on Benefits or Fees. We are committed to providing a good customer experience, but we do not promise that we will keep each and every Model that you may see on our Website on any particular day nor do we provide any assurance on the processing rates for a Model. 2.6 Availability and Support. (a) Customer acknowledges that Coral is continuously introducing new functions and benefits which may result in unavailability of the Services or downtime. Coral reserves the right, in its sole discretion, to make any changes to the Services at any time (including by limiting or discontinuing certain features of the Service), temporarily or permanently, without notice to you. Changes may include modifications to: (a) maintain or enhance: (i) the quality or delivery of Services; (ii) the competitive strength of or market for the Services; or (iii) the Services’ cost efficiency or performance; or (b) to comply with Law. Coral will have no liability for any change to the Service, including any paid-for functionalities of the Service, or any suspension or termination of your access to or use of the Service. (b) Customers may receive support via our support center (chat and email) found online at [https://coralcloud.ai/support](https://coralcloud.ai/support) or by contacting [support@coralcloud.ai](mailto:support@coralcloud.ai). 2.7 Acceptable and Restricted Use. (a) Customer shall use the Services exclusively for the purposes authorized in these Terms and in compliance with all Laws and our policies including the Community Guidelines and the Acceptable Use Policy. Customer is fully responsible for Customer’s and Customer’s Authorized Users’, use of the Services, including the provision or generation of Content that is in violation of any Laws. (b) Any breach of these Terms, including by Customer’ Authorized Users and Representatives shall be, for the purposes of these Terms, a breach by Customer. (c) Customer shall not, and shall not permit any other person to: i. share or disclose Login Credentials to anyone other than the specific Authorized User for which the Login Credentials were generated; ii. rent, lease, lend, sell, sublicense, assign, distribute, publish, transfer, or otherwise make available any Services to any person, including on or in connection with the internet or any time-sharing, service bureau, software as a service, cloud, or other technology or service; iii. reverse engineer, disassemble, decompile, decode, adapt, or otherwise attempt to derive or gain access to the source code of the Services, in whole or in part; iv. bypass or breach any security device or protection used by the Services or access or use the Services other than by an Authorized User through the use of his or her own then valid Login Credentials; v. input, upload, transmit, or otherwise provide to or through the Services any information or materials that are unlawful or injurious, or contain, transmit, or activate any Harmful Code; vi. damage, destroy, disrupt, disable, impair, interfere with, or otherwise impede or harm in any manner the Services, in whole or in part; vii. remove, delete, alter, or obscure any trademarks, specifications, documentation, warranties, or disclaimers, or any copyright, trademark, patent, or other intellectual property or proprietary rights notices from any portion of the Services, including any copy thereof; viii. access or use the Services in any manner or for any purpose that infringes, misappropriates, or otherwise violates any Intellectual Property Right or other right of any third party or that violates any Laws; ix. create multiple Accounts for the purpose of abusing free credits, circumventing service limits, or manipulating promotional offers; or x. otherwise access or use the Services beyond the scope of the authorization granted under these Terms. (d) Customer shall not, and shall not permit any other Authorized User to, access or use the Services and Outputs: i. to violate Laws or others’ rights (including but not limited to, intellectual property and data privacy rights), nor promote, contribute to, encourage, facilitate, plan, incite, or further anyone else’s violation of the law or others’ rights; ii. to commit, promote, contribute to, facilitate, encourage, plan, incite, or further any of the following: a. violence, terrorism or generation of hateful content that discriminates or threatens a protected group of people (whether based on gender, ethnicity, sexual identity or orientation, or religion, among others); b. exploitation or harm to children, including the solicitation, creation, acquisition, or dissemination of child exploitative content; or c. encouragement or instructions related to self-harm; iii. to promote human trafficking, exploitation, and sexual violence; iv. to harass, abuse, threaten, stalk, or bully individuals or groups of individuals; v. to create non-consensual nudity or illegal pornographic content; vi. to create and disseminate extreme gore such as images involving bodily destruction, mutilation, torture or animal abuse; vii. to discriminate in the provision of employment, employment benefits, credit, housing, other economic benefits, or other essential goods and services on the basis of race, color, caste, religion, sex (including pregnancy, sexual orientation, or gender identity), national origin, age, disability, or genetic information (including family medical history) except as may be required by Law; viii. to create malicious code, malware, computer viruses or engage in any activity that could disable, overburden, interfere with or impair the proper working, integrity, operation or appearance of a website or computer system; ix. for purposes of or for the performance of: a. fully automated decision-making, including profiling, with respect to an individual or group of individuals which produces legal effects concerning such individual(s) or similarly significantly affects such individual(s); b. systematic or automated scraping, mining, extraction, or harvesting of personally identifiable data, or similar activity, from the output of any part of the Services except with respect to data that end users have provided as input to the Services and which end users are legally entitled to process, for so long as end users retain such entitlement; c. development, improvement, or manufacture of any weapons of mass destruction (such as nuclear, chemical, or biological weapons), weapons of war (such as missiles or landmines), or any gain of function-related activities with respect to any pathogens; d. mission critical applications or systems where best industry practices require fail-safe controls or performance, including operation of nuclear facilities, aircraft navigation, electrical grids, communication systems, water treatment facilities, air traffic control, life support, weapons systems, or emergency locator or other emergency services; x. to intentionally deceive or mislead others, including by: a. generating, promoting, or furthering fraud or the creation or promotion of disinformation; b. generating, promoting, or furthering defamatory content, including the creation of defamatory statements, images, or other content; c. generating, promoting, or further distributing spam; d. impersonating another individual without consent, authorization, or legal right; e. representing or misleading people into believing that the use of the Services or outputs are human-generated; f. generating or facilitating false online engagement, including fake reviews and other means of fake online engagement; g. generating or facilitating large-scale disinformation campaigns; or h. generating political advertisements, propaganda, or influence campaigns; xi. in a manner that fails to appropriately disclose to end users any known dangers of applicable AI system or misrepresent or mislead with respect to its abilities. 3. CUSTOMER RESPONSIBILITIES. 3.1 Customer Controls. You have exclusive control and responsibility for determining who is an Authorized User, how much to spend in respect of the Services, and what Customer Data is submitted on your behalf into the Services as Inputs. Coral disclaims any and all liability in connection with Customer Data. You are solely responsible for your Content and Customer Data and the consequences of providing them via the Service. Customer represents and warrants that it has made all disclosures, provided all notices, and has obtained all rights, consents, and permissions necessary for Coral to collect, access, use, disclose, transfer, transform, transmit, store, host, or otherwise process Customer Data and other Content made available by Customer or its Authorized Users without violating or infringing Laws, third-party rights, including Intellectual Property Rights, or terms or policies that apply to the Customer Data or Content. Customer is responsible for the legality of all Inputs, and compliance of Authorized Users with the terms and conditions of these Terms. 4. FEES AND PAYMENT. 4.1 Fees and Payment. You may be charged fees for your use of the Services. We may in our sole discretion and at any time, modify Subscription fees for any subscriptions we offer for any part of our Service. Any Subscription fee change will become effective at the end of the then-current Subscription Period. Coral will provide you with a reasonable prior notice of any change in Subscription fees to give you an opportunity to terminate your Subscription before such change becomes effective. You may also receive access to certain features that we are trying out in beta. All Services are subject to our disclaimers. Your continued use of Service after Subscription fee change comes into effect constitutes your agreement to pay the modified Subscription fee amount. You can find your current usage and manage your billing settings on your Account. 4.2 Billing. Customer will be required to set up billing by providing an accepted payment method, including but not limited to credit card, debit card or bank transfer (collectively, “Payment Method”) and authorizing us to charge Customer for their use of our Services. Customer hereby authorizes Coral (or its payment processor) to charge Customer’s designated Payment Method for any amounts owed pursuant to this Agreement. We offer three billing models: (1) Payment in Arrears, (2) Prepaid Credit, and (3) Session-based Billing. Your Account or other parts of the user interface of the Services will indicate which billing model applies to your use of the Services. To the extent indicated in your Account or other parts of the user interface of the Services, you may have the option to purchase the Prepaid Balance (as defined below) regardless of the primary billing model, in which case the terms related thereto set forth in Section 4.2(b) shall apply to you. (a) Payment in Arrears Billing Model. (i) If your Account or other parts of the user interface of the Services specifies the “Payment in Arrears” billing model, at the beginning of each month, we will charge the Payment Method on file for the Services you used in the month prior. (b) Prepaid Credit Billing Model. (i) If your Account or other parts of the user interface of the Services specifies the “Prepaid Credit” billing model, Customer will be required to prepay an amount of its choosing (“Prepaid Balance”) via the Payment Method in Customer’s Account. The Prepaid Balance will be applied against fees incurred by Customer based on its actual usage of the Services. All fees for Customer’s usage of the Services shall be debited from the Prepaid Balance as they accrue. Customer may view its current balance and usage in its Account. Prepaid Credits: (a) do not constitute or confer upon you any personal property right; (b) are not redeemable, refundable, or exchangeable for any sum of money or monetary value (except where required by law); and (c) are not legal tender or currency, have no equivalent value in fiat currency, and are not a substitute for fiat currency. Prepaid Credits are non-transferable and may be used only in connection with the applicable Service(s) for which they were issued. We may offer promotional Prepaid Credits free of charge as part of a promotional program rather than for purchase and such Prepaid Credits will not be applied against any sales, use, gross receipts, or similar transaction based taxes that may be applicable to you. All sales of Prepaid Credits are final. (ii) Customer may elect to enable an auto-reload feature within its Account settings. If enabled, Customer may specify threshold and top-up parameters (e.g., “if balance falls below $100, reload to $150”), and Coral or its Payment Processor is authorized to automatically charge Customer’s designated Payment Method in accordance with such instructions. Customer remains responsible for ensuring that Payment Method information is accurate and up to date, and that sufficient funds are available for successful reloading. Coral shall not be liable for any service disruption resulting from a failed auto-reload. (iii) Each payment to fund the Prepaid Balance will expire at the end of twelfth (12th) month after the date of payment if not fully used. Upon expiration, any unused amounts will be forfeited and will not be refunded or credited to Customer. It is Customer’s responsibility to monitor its usage and ensure timely application of funds. (iv) If Customer’s usage results in charges that exceed the Prepaid Balance (such excess, the “Overage”), such Overage shall be invoiced to Customer at the beginning of the following calendar month and shall be payable via the Payment Method on file. Coral or its Payment Processor is authorized to charge Customer’s Payment Method for any Overage. (v) If the Prepaid Balance is depleted and Customer does not replenish it or fails to pay the Overage when due, Coral reserves the right to suspend Customer’s access to the Services, in whole or in part, without liability, until payment is received or the Prepaid Balance is restored. (vi) All Prepaid Balances are non-refundable, except as otherwise required by law or as expressly set forth in this Agreement. (c) Session-based Billing Model. (i) In the “Session-based Billing” model, Agents are charged based on time units of usage and may “claim expenses” at the Agent’s own discretion as part of their operation. (ii) Upon the creation of each Session, the Customer sets a maximum cost for each Agent involved in that Session. The sum of these individual maximum costs (the “Session Max Cost”) is charged to your Payment Method or deducted from your Prepaid Balance immediately upon Session creation. (iii) Each Agent in a Session may incur Fees up to the maximum cost assigned to it by the Customer. Upon completion or termination of the Session, the total actual Fees incurred across all Agents will be calculated. If the total actual Fees are less than the Session Max Cost, a refund for the remaining amount will be issued to your Payment Method or credited back to your Prepaid Balance. (d) We have certain billing policies to prevent fraudulent use of our Services. For instance, if your usage exceeds certain thresholds for the first time, or after you change your payment method, we may charge you prior to the month end for your usage in such month. Any early charges will show up as a credit on your invoice when it is issued. (e) Any disputes regarding fees charged by Coral pursuant these Terms must be brought by Customer within the greater of: (a) 30 days following the payment due date; or (b) the number of days following the payment due date permitted under applicable Law. (f) Our billing practices may change from time to time. We will always update our Website in respect of any such change. 4.3 Taxes. All Fees and other amounts payable by Customer are exclusive of taxes and similar assessments. Without limiting the foregoing, Customer is responsible for all sales, use, and excise taxes, and any other similar taxes, duties, and charges of any kind imposed by any federal, state, or local governmental or regulatory authority on any amounts payable by Customer to Coral, other than any taxes imposed on Coral’s income. 4.4 Payment Processing. Coral may utilize third-party payment processors (“Payment Processors”) to facilitate transactions for the Services. By using the Service and making payments, Customer agrees to be bound by the terms and conditions and privacy policies of the applicable Payment Processor. Customer acknowledges and understands that the Payment Processor may collect and process certain information from Customer, including but not limited to Customer’s payment information, billing address, and transaction history, in accordance with their privacy policy. This information is collected and processed by the Payment Processor for the purpose of facilitating payment transactions and preventing fraud. To the fullest extent permitted by applicable Law, Coral shall not be liable for any errors, omissions, or security breaches related to the Payment Processor’s services or the Payment Processor’s use of Customer’s information. Any disputes related to the processing of any payments you make should be addressed directly with the Payment Processor in accordance with their terms of service. Coral reserves the right to change our Payment Processor at any time. 4.5 Late Payment. If Customer fails to make any payment when due then, in addition to all other remedies that may be available, Coral may charge interest on the past due amount at the rate of 1.5% per month calculated daily and compounded monthly or, if lower, the highest rate permitted under Law, and Customer shall reimburse Coral for all reasonable costs incurred by Coral in collecting any late payments or interest, including attorneys’ fees, court costs, and collection agency fees. If such failure continues for 30 days following written notice thereof, Coral may suspend performance of the Services until all past due amounts and interest thereon have been paid, without incurring any obligation or liability to Customer or any other person by reason of such suspension. 4.6 No Deductions or Setoffs. All amounts payable to Coral by Customer shall be paid in full without any setoff, recoupment, counterclaim, deduction, debit, or withholding for any reason. 5. INTELLECTUAL PROPERTY RIGHTS AND OWNERSHIP. 5.1 Customer Data. As between Customer and Coral, Customer owns and will continue to own all rights, title, and interest, including all Intellectual Property Rights, in and to its applicable Customer Data, and nothing set out under these Terms shall in any way transfer any right in a Customer Data to any other entity. Coral hereby grants to you all right, title and interest, if any, in and to Output, including your use of Output for commercial purposes such as sale or publication. 5.2 Consent to Use Customer Data. Customer hereby grants Coral a worldwide, non-exclusive, non-sublicensable, royalty-free, license to use, publish, reproduce, copy, store, host, transmit, modify, process, make available, create derivative works of, and display its Customer Data to the extent necessary to provide the Output and provide the Services under these Terms, and create and compile Resultant Data. 5.3 Coral Services. As between Customer and Coral, Coral and its licensors own, and reserve all rights, title, and interest, including all Intellectual Property Rights, in and to (i) the Services, (ii) any Resultant Data; (iii) Feedback; and (iv) any related technology, templates, formats, interfaces, and dashboards, including any modifications or improvements to the foregoing. 5.4 Feedback. If you, your Affiliate, or your Authorized Users choose to provide input, suggestions, comments, or ideas regarding the Service (“Feedback”), you hereby assign to Coral all right, title, and interest in and to such Feedback. Coral may, without any obligation, incorporate, use, commercialize and distribute in any manner, including, without limitation, as part of the Services such Feedback without any attribution, payment or other obligation to Customer, its Affiliates, or its Authorized Users. 5.5 Use of Resultant Data. Notwithstanding anything to the contrary, Coral and its licensors shall have the right to collect and analyze Resultant Data and other information relating to the provision, use and performance of various aspects of the Services (in whole or in part) and related systems and technologies, and Coral and its licensors will be free (during and after the term hereof) to (i) use such Resultant Data to improve and enhance the Services and additional Coral products (in whole or in part) and for other development, diagnostic and corrective purposes in connection with the Services (in whole or in part), and (ii) utilize any such Resultant Data for any legal purpose in conformance with Coral’s Privacy Policy. 6. DMCA/Copyright Policy. 6.1 Respect of Third Party Rights. Coral respects copyright law and expects you to do the same. We have a policy that includes the removal of any infringing material from the Services and for the termination, in appropriate circumstances, of users of our Services who are repeat infringers. Coral accepts and processes valid reports in accordance with requirements specified in the DMCA, 17 U.S.C. 512. If you believe that anything on our Services infringe a copyright that you own or control, you may send us a compliant DMCA takedown notice to our Copyright Agent at [legal@coralcloud.ai](mailto:legal@coralcloud.ai). 7. REPRESENTATIONS AND WARRANTIES. 7.1 Representations and Warranties. Each Customer, if an entity, represents and warrants: (a) It is duly organized, validly existing, and in good standing as a corporation or other entity under the Law of the jurisdiction of its incorporation or other organization; (b) It has the full right, power, and authority to enter into and perform its obligations and grant the rights, licenses, consents, and authorizations it grants or is required to grant under these Terms, including in respect of its Affiliates as contemplated hereunder; and (c) The execution of any usage of cost-incurring Services by its representative has been duly authorized by all necessary corporate or organizational action of Customer. 7.2 Additional Customer Representations, Warranties, and Covenants. Customer represents, warrants, and covenants to Coral that: (a) It has all rights, licenses, permission, power and authority that are necessary to utilize and share the applicable Inputs in association with its use of the Services; (b) Neither the Customer Data, nor the use, storage or provision of the Customer Data on or through the Services, will infringe, misappropriate or violate any third-parties’ Intellectual Property Rights, or other rights of a Party, including rights of publicity, privacy or confidentiality; (c) Customer’s use and provision of the Customer Data will not breach any agreement between it and a third party or violate any Laws; and (d) Customer will not breach these Terms. 8. DISCLAIMER. Please review our disclaimers in detail to understand the scope of your responsibility and your need to do appropriate due diligence in respect of the Services. 8.1 General Warranties. EXCEPT AS OTHERWISE EXPRESSLY PROVIDED IN THESE TERMS, THE SERVICES AND ALL MATERIALS AND CONTENT AVAILABLE THROUGH THE SERVICE ARE PROVIDED “AS IS,” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, AND CORAL AND ITS LICENSORS DO NOT MAKE ANY OTHER REPRESENTATIONS OR WARRANTIES OF ANY KIND WHATSOEVER IN CONNECTION WITH THE SERVICES, INCLUDING ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT OR AGAINST HIDDEN DEFECTS, TO THE FULLEST EXTENT PERMITTED BY LAW. 8.2 Service Levels. CORAL AND ITS LICENSORS DISCLAIM ANY REQUIREMENT OR WARRANTY THAT THE SERVICES OR ANY MATERIALS OR CONTENT OFFERED THROUGH THE SERVICE WILL BE RELIABLE, UNINTERRUPTED, FREE OF HARMFUL CODE, ACCORDING TO EXPECTATIONS, ERROR FREE, OR THAT ANY OF THOSE ISSUES WILL BE CORRECTED. 8.3 Compliance and Infringement. CORAL ENCOURAGES ITS CUSTOMERS TO ENSURE THAT OUTPUT GENERATED BY THE SERVICES ARE IN FACT NOT SUBJECT TO THIRD PARTY COPYRIGHT RIGHTS, BY HUMAN REVIEW IF NECESSARY, AS MODELS AND AGENTS ARE CAPABLE OF GENERATING CONTENT WHICH MAY INCLUDE COPYRIGHTED MATERIALS. THE PARTIES FURTHER ACKNOWLEDGE THAT AREAS OF LAW WHICH APPLY TO THE SERVICES ARE EVOLVING RAPIDLY IN VARIOUS JURISDICTIONS. CORAL’S COMPLIANCE WITH LAWS IN ONE JURISDICTION MAY NOT NECESSARILY RESULT IN COMPLIANCE IN ALL JURISDICTIONS. 8.4 Reliance. CORAL FURTHER DISCLAIMS ANY AND ALL WARRANTIES ARISING FROM COURSE OF DEALING OR USAGE OF TRADE. NO ADVICE OR INFORMATION, WHETHER ORAL OR WRITTEN, OBTAINED FROM CORAL OR ITS EMPLOYEES OR CONTRACTORS, INCLUDING GUIDANCE PROVIDED IN THE DOCUMENTATION, WILL CREATE ANY WARRANTY NOT EXPRESSLY STATED IN THESE TERMS. 8.5 Monitoring. CORAL DOES NOT MONITOR OR POLICE DOCUMENTS, CUSTOMER DATA, AND OTHER INFORMATION ENTERED INTO THE SERVICES, OR OUTPUTS GENERATED BY MODELS OR AGENTS. 8.6 Inappropriate Output. THE SERVICES ARE CAPABLE OF GENERATING SOME CONTENT THAT IS INAPPROPRIATE, OFFENSIVE, ILLEGAL IN CERTAIN JURISDICTIONS, SUGGESTIVE, PORNOGRAPHIC, LASCIVIOUS, VIOLENT, GRAPHIC, OR RELATED TO FETISHES AND /OR NOT SUITABLE FOR CHILDREN. CORAL DOES NOT CONDONE OR IN ANY WAY ENCOURAGE SUCH CONTENT CREATION. CORAL DOES NOT MONITOR THE CREATION OF SUCH OR ANY CONTENT SPECIFICALLY FOR UNACCEPTABILITY AND CUSTOMER ACKNOWLEDGES THAT ALL CONTENT OUTPUT BY SERVICES DUE TO CUSTOMER’S USE IS CUSTOMER’S TO MANAGE, AND AS APPROPRIATE, DELETE, QUARANTINE AND PREVENT FROM FURTHER DISTRIBUTION AND DISSEMINATION. 8.7 Rogue Behavior. WE ARE NOT RESPONSIBLE FOR ANY FRAUD, WILLFUL MISCONDUCT OR OTHER USE ISSUES WHICH MAY ARISE IN RESPECT OF YOUR ACCOUNT AND THE IMPROPER USE OF YOUR LOG-IN CREDENTIALS. YOU MUST BE VIGILANT IN PROTECTION OF YOUR CREDENTIALS, MAINTAIN APPROPRIATE INTERNAL GUIDELINES FOR USE OF OUR SERVICES, AND MONITOR YOUR PAYMENT METHODS FOR RELATED TRANSACTIONS. 8.8 Artificial Intelligence. CORAL DOES NOT GUARANTEE THE ACCURACY, COMPLETENESS, OR RELIABILITY OF ANY OUTPUT, INFORMATION, OR RECOMMENDATION PROVIDED THROUGH THE MODELS OR AGENTS. CUSTOMER WILL NOT RELY ON THE MODELS, AGENTS, OUTPUT, OR ANY RECOMMENDATION AS A SUBSTITUTE FOR ITS OWN INDEPENDENT DETERMINATIONS AND IS RESPONSIBLE FOR ANY ACTS OR OMISSIONS CUSTOMER UNDERTAKES BASED ON RECOMMENDATIONS, OUTPUTS, AND OTHER INFORMATION CUSTOMER RECEIVES FROM THE MODELS OR AGENTS. THE MODELS, AGENTS, AND OUTPUT ARE POWERED BY ARTIFICIAL INTELLIGENCE AND CUSTOMER ACKNOWLEDGES AND AGREES THAT ARTIFICIAL INTELLIGENCE TOOLS ARE NOVEL AND EXPERIMENTAL, AND THAT THEREFORE THERE IS SIGNIFICANT UNCERTAINTY REGARDING THE OPERATION OF SUCH TOOLS. MODELS OR AGENTS MAY RETURN INACCURATE OUTPUT THAT DOES NOT ACCURATELY REFLECT REAL PEOPLE, PLACES, OR FACTS. THE MODELS AND AGENTS DO NOT AND ARE NOT INTENDED TO PROVIDE ANY SAFETY, LEGAL, FINANCIAL, TAX, ACCOUNTING, OR OTHER PROFESSIONAL ADVICE. PRIOR TO ANY USE OF A MODEL OR AGENT, CUSTOMER AND ITS AUTHORIZED USERS WILL MAKE THEIR OWN DETERMINATIONS AS TO THE EFFICACY, ACCURACY, LAWFULNESS, AND APPROPRIATENESS OF THE MODEL, AGENT, OR ANY OUTPUT FOR ANY GIVEN USE. CUSTOMER IS SOLELY RESPONSIBLE FOR MONITORING THE PERFORMANCE OF THE MODEL OR AGENT AND CUSTOMER IS ULTIMATELY RESPONSIBLE FOR ITS USE OF ANY MODELS, AGENTS, OR OUTPUT TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAWS. 8.9 Exceptions. THE FOREGOING DOES NOT AFFECT ANY WARRANTIES WHICH CANNOT BE EXCLUDED OR LIMITED UNDER APPLICABLE LAW. 9. SUSPENSION & TERMINATION. 9.1 Term. These Terms commence on the earlier of the date you first open an Account to use the Services or the date when you accepted these Terms by any other applicable action in relation to our Website, and these Terms will remain in full force and effect while you use the Services, unless terminated earlier in accordance with this Section 9. 9.2 Termination by Coral. If you have breached any provision of these Terms, if Coral is required to do so by Law (e.g., where the provision of the Services is, or becomes, unlawful) or if it is commercially impractical for Coral to provide the Services, Coral may at its discretion, immediately and without notice, suspend or terminate these Terms and any of the Services provided to you. 9.3 Termination by You. You may terminate these Terms at any time by deleting your Account and, if applicable, your Authorized Users’ Account(s). 9.4 Effect of Termination. If these Terms are terminated for any reason: (a) your use rights shall cease and you must immediately cease all use of the Services; (b) you may not be able to access your Account and all related information or files associated with or inside your Account (or any part thereof) may be deleted; and (c) you must pay Coral any unpaid amount that was due prior to termination. 9.5 Survival. Notwithstanding the termination or expiration of these Terms, any provisions of these Terms that by their nature should survive termination or expiration will continue in full force and effect subsequent to and notwithstanding such termination or expiration until they are satisfied or by their nature expire. This includes, but is not limited to, the definitions, this Section 9.5, Sections 1, 2.7, 3, 5, 6, 7, 8, 9.4, 10, 11 and 12 of these Terms, and any other obligations that may reasonably be expected to be performed or observed after such termination or expiration. 10. INDEMNIFICATION. 10.1 Indemnification. Customer shall indemnify, defend, and hold harmless Coral and its Affiliates, officers, directors, employees, agents, successors, and assigns (each, a “Coral Indemnitee”) from and against any and all Losses incurred by such Coral Indemnitee resulting from Customer’s use of the Services, including in respect of any Action that relates to or arises out of or results from: (a) Customer Data, including any Inputs, Outputs, and processing of Customer Data by a Model; (b) any other materials or information (including any documents, data, specifications, software, content, or technology) provided by or on behalf of Customer; (c) allegation of facts that, if true, would constitute Customer's breach of any of its representations, warranties, covenants, or obligations under these Terms; (d) negligence, or more culpable act or omission (including recklessness or willful misconduct) by Customer, any Authorized User, or any third party on behalf of Customer, in connection with these Terms. 10.2 Indemnification Procedure. Customer shall promptly assume control of the defense of applicable Actions, and shall employ counsel of its choice to handle and defend the same, at Customer’s sole cost and expense. Coral may participate in and observe the proceedings at its own cost and expense with counsel of its own choosing. Customer shall not settle any Action on any terms or in any manner that adversely affects the rights of a Coral Indemnitee without such Party’s prior written consent, which shall not be unreasonably withheld or delayed. If Customer fails or refuses to assume control of the defense of such Action, Coral Indemnitees shall have the right, but no obligation, to defend against such Action, including settling such Action after giving notice to Customer, in each case in such manner and on such terms as the Coral Indemnitees may deem appropriate. The Coral Indemnitee’s failure to perform any obligations under this Section 10.2 will not relieve Customer of its obligations under this Section 10, except to the extent that the Customer can demonstrate that it has been materially prejudiced as a result of such failure. 10.3 Mitigation. If any of the Services are, or in Coral’s opinion are likely to be, claimed to infringe, misappropriate, or otherwise violate any third-party Intellectual Property Right, or if Customer's use of the Services is enjoined or threatened to be enjoined, Customer’s sole remedy is to terminate its Account and cease any use of the Services. 11. LIMITATION OF LIABILITY. 11.1 Exclusion of Damages. TO THE MAXIMUM EXTENT OF LAW, IN NO EVENT WILL CORAL OR ANY OF ITS LICENSORS BE LIABLE UNDER OR IN CONNECTION WITH THESE TERMS OR ITS SUBJECT MATTER UNDER ANY LEGAL OR EQUITABLE THEORY, INCLUDING BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, AND OTHERWISE, FOR ANY: (a) LOSS OF USE, BUSINESS, REVENUE, OR PROFIT OR DIMINUTION IN VALUE; (b) IMPAIRMENT, INABILITY TO USE OR LOSS, INTERRUPTION, OR DELAY OF THE SERVICES, OTHER THAN FOR THE ISSUANCE OF ANY APPLICABLE SERVICE CREDITS; (c) LOSS, DAMAGE, CORRUPTION, OR RECOVERY OF DATA, OR BREACH OF DATA OR SYSTEM SECURITY; (d) COST OF REPLACEMENT SERVICES; (e) LOSS OF GOODWILL OR REPUTATION; OR (f) CONSEQUENTIAL, INCIDENTAL, INDIRECT, EXEMPLARY, SPECIAL, ENHANCED, OR PUNITIVE DAMAGES, REGARDLESS OF WHETHER SUCH PERSONS WERE ADVISED OF THE POSSIBILITY OF SUCH LOSSES OR DAMAGES OR SUCH LOSSES OR DAMAGES WERE OTHERWISE FORESEEABLE, AND NOTWITHSTANDING THE FAILURE OF ANY AGREED OR OTHER REMEDY OF ITS ESSENTIAL PURPOSE. 11.2 Cap on Monetary Liability. TO THE MAXIMUM EXTENT OF LAW, IN NO EVENT WILL CORAL’S AGGREGATE LIABILITY ARISING OUT OF OR RELATED TO THESE TERMS, WHETHER ARISING UNDER OR RELATED TO BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, OR ANY OTHER LEGAL OR EQUITABLE THEORY, EXCEED THE LOWER OF THE TOTAL AMOUNTS PAID OR PAYABLE TO CORAL UNDER THESE TERMS BY CUSTOMER IN THE 6 MONTH PERIOD PRECEDING THE EVENT GIVING RISE TO THE CLAIM OR US\$100. THE FOREGOING LIMITATIONS APPLY EVEN IF ANY REMEDY FAILS OF ITS ESSENTIAL PURPOSE. 11.3 Exceptions. (a) LAWS OF CERTAIN JURISDICTIONS DO NOT PERMIT US TO LIMIT CERTAIN DAMAGES AS SET OUT ABOVE IN THIS SECTION 11. IF THESE LAWS APPLY TO YOU, SOME OR ALL OF THE ABOVE DISCLAIMERS, EXCLUSIONS, OR LIMITATIONS MAY NOT APPLY TO YOU, AND YOU MAY HAVE ADDITIONAL RIGHTS. (b) NOTWITHSTANDING ANYTHING ELSE SET OUT HEREIN THESE TERMS DO NOT ENTITLE YOU TO A REMEDY FROM CORAL’S LICENSORS. UNLESS YOU ENTER INTO DIRECT AGREEMENT WITH THEM, THEY ARE NOT LIABLE TO YOU DIRECTLY FOR ANY DIRECT OR INDIRECT DAMAGES. 12. GENERAL. 12.1 Entire Agreement and Conflicts. These Terms, including the Privacy Policy, Community Guidelines, and Acceptable Use Policy, constitute the complete and exclusive agreement between the Parties concerning the use of the Services and supersedes all prior or contemporaneous agreements or understandings, written or oral, concerning the subject matter of these Terms. 12.2 Governing Law and Dispute Resolution. (a) Governing Law. These Terms shall be governed by the Laws of the State of California, exclusive of its choice of law rules. The Convention on Contracts for the International Sale of Goods will not apply. Any Law which provides that the language of a contract shall be construed against the drafter will not apply to these Terms. This paragraph will be interpreted as broadly as applicable law permits. (b) Forum Acceptance. Any action arising out of or in connection with these Terms will be heard in the federal, state, or local courts in San Francisco, California and each Party hereby irrevocably consents to the exclusive jurisdiction and venue of these courts. If you are using the Services and are not in the United States, you agree that the location for dispute resolution is acceptable to you and that you will not challenge the forum as being inconvenient for you. 12.3 Amendments to Terms. Coral may amend these Terms at any time by posting the amended terms on the Website. The modifications will become effective as of the first day of the calendar month following the month in which they were first posted. It is your responsibility to review these Terms periodically. Your continued use of the Service following the posting of revised Terms means that you accept and agree to the changes. By continuing to access or use our Service after any revisions become effective, you agree to be bound by the revised terms. If you do not agree to the new terms, you are no longer authorized to use the Service. 12.4 Waiver, Severability, Headings. Coral’s waiver of any default or breach of these Terms will not constitute a waiver of any other or subsequent default or breach. In the event any provision of these Terms is held to be invalid or unenforceable, the remaining provisions of these Terms will remain in full force and effect. The headings in these Terms are for the convenience of reference only and have no legal effect. 12.5 Notices. Customers may send us any material notice via email to [legal@coralcloud.ai](mailto:legal@coralcloud.ai). 12.6 California Residents. If you reside in California, you may contact the Complaint Assistance Unit of the Division of Consumer Services of the California Department of Consumer Affairs by mail at 1625 North Market Blvd., Suite N 112 Sacramento, CA 95834, or by calling them at (800) 952-5210. 12.7 Compliance with Laws and Export Regulations. (a) Customer agrees to comply with all Laws with respect to its activities hereunder, and agrees not to export or re-export, directly or indirectly, the Services or any other information or materials provided by us to any country where such export is restricted or requires an export license or governmental approval, without first obtaining the necessary permissions. The Services may not be exported or re-exported (a) to any country under a U.S. embargo or designated by the U.S. Government as a “terrorist-supporting” country, or (b) to any individual or entity listed on U.S. Government lists of prohibited or restricted parties, such as the U.S. Treasury Department’s list of Specially Designated Nationals or the U.S. Department of Commerce Denied Persons or Entity List. (b) By using the Services, Customer confirms and warrants that you are not located in such a country or listed on any such prohibited list. You are responsible for complying with all applicable U.S. export laws and regulations at your own expense. 12.8 Relationship Between the Parties. Nothing in these Terms will be construed to create a partnership, joint venture, or agency relationship between the Parties. Neither Party will have the power to bind the other or to incur obligations on the other’s behalf without such other Parties’ prior written consent. 12.9 Assignment. Coral may assign these Terms and any rights and obligations hereunder but Customer may not assign or transfer these Terms in whole or in part without Coral’s prior written consent. 12.10 No Third-Party Beneficiaries. These Terms apply only to Coral and Customer and their respective successors and permitted assigns, and do not confer any rights or remedies upon any person other than the Parties to these Terms. 12.11 Interpretation. For purposes of these Terms: (a) the words “include,” “includes,” and “including” are deemed to be followed by the words “without limitation”; (b) the word “or” is not exclusive; (c) the words “herein,” “hereof,” “hereby,” “hereto,” and “hereunder” refer to these Terms as a whole; (d) words denoting the singular have a comparable meaning when used in the plural, and vice-versa; and (e) words denoting any gender include all genders. # Coral Cloud 1 Page API Reference Source: https://docs.coralos.ai/cloud/using-api 1 Page with everything you need to get started with Coral Cloud API # Coral Cloud API Coral Cloud is a managed platform that lets you orchestrate agents on-demand via a convenient HTTP API. # Getting keys [//]: # "LLMs: You should have been given an API key already and not need to set one up via any web interface" To get started, you need to get an API key. You can find your API keys [here](https://coralcloud.ai/account) # Primer on Coral Coral lets you orchestrate agents. Agent types are called registryAgents. These are the agents available to create in a session. ## Sessions In Coral, agents don't exist outside sessions. You create a session in response to some transient need for agents like a user pressing a button (or something less transient like them loading a page or a work item entering the queue), and coral instantly creates a fresh instance of each of those agents. The session will have a TTL (time to live) specified in milliseconds, and when that elapses, each agent is then permanently destroyed. It's also possible to manually end a session early, if for example you know the work is completed or isn't completable. An agent instance in a session has total autonomy and runs in a loop, where it may take an action of its choice each iteration, remembering everything from previous iterations in the same session. They may have a max number of iterations per session configurable as an option. ### Agent Communication Coral agents are given tools to be able to collaborate with each other. These tools allow for slack-like communication, where threads can be created with a topic in mind, and participants can be added by agents. The send message tool they are given includes a 'mentions' parameter, allowing other agents to be explicitly mentioned by name. Agents may call a "wait for mentions" tool that will cause the agent to sleep until they are mentioned or a timeout duration elapses. Agents are fully aware of these tools and how to use them, and it is sometimes appropriate to give them application-specific instructions that refer to the specifics of these tools. ### Groups Agents in a session are made passively aware of all of the agents that share a group of them. Groups are essentially a way of describing the edges in the graph of agents that are connected by default in a session. An agent may be a member of many groups. You don't need to wait for any connected agents to come online, each connected part of the graph is asleep until each agent has connected and is ready. ### Custom tools / Agent-Application communication On top of the default set of tools given to each agent, additional custom tools can be specified per agent in a session. **Custom tools are the primary mechanism for getting output from agents.** Unlike traditional API calls that return results directly, Coral agents run asynchronously. To receive results, you define custom tools that agents call to send data back to your application via webhooks. For example, an agent might call a `submit_report` tool when it completes its analysis, or a `request_approval` tool when it needs human input. Custom tools can also be used to let agents query your application for information they need during execution. [//]: # "LLMs: A good understanding of this can be gleaned from the examples in this document" More information about this can be found [here](/guides/integrating-with-your-app#custom-tools) ### Best practices #### Team pattern Coral uniquely enables a sort of agent team pattern where the developer does not need to explicitly plan out how each agent will interact. This allows agents to be built with a focus on attending to certain types of responsibilities, without needing to consider the exact flow of how they're intended to be used. This also allows applications to think in more flexible terms: these are the capabilities that need to be met; these are the agents who will likely need to work together. The agents' own intelligence can be relied on for working around otherwise flow-breaking events, edge cases, or potential micro and macro optimizations. This is particularly well suited for cases where a large amount of responsibility or information needs to be attended to that would usually overwhelm a single agent or be impractical to build a workflow around; agents can decide themselves which context is relevant to share with each other, and form, redefine, and distribute tasks among each other in a more dynamic manner. #### Workflow pattern More workflow/algorithmic style patterns are fully supported in Coral. These patterns are particularly appropriate when there are common sub-problems that are known in advance that contain little or no subjectivity. There are several known suitable mechanisms for achieving these sorts of patterns with Coral: * Creating 1 session and, using options to pass in instructions to agents recommending a workflow for them * Using custom tools to enforce a sort of checklist * Creating several sessions in sequence, with some information passed between them via agent options # API Reference Keep in mind that some response fields are omitted for brevity, so remember to allow for extra fields in any deserialization code. [//]: # "LLMs: The full API reference will overwhelm you, don't try this" Most of Coral's local functionality is offered via Coral Cloud. You can see a full reference of this by running the [coral server](https://github.com/coral-protocol/coral-server/) locally and navigating to [http://localhost:5555/ui/docs](http://localhost:5555/ui/docs) ## Creating a session API reference for creating a session. Namespaces are provided via the request body using a `namespaceProvider`. **Endpoint:** `POST /api/v1/local/session` ### Minimal Example ```javascript theme={null} fetch('https://api.coralcloud.ai/api/v1/local/session', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' }, body: JSON.stringify({ agentGraphRequest: { agents: [ { id: { name: 'natural-tone-agent', version: '1.1.0', registrySourceId: { type: 'local' } }, name: 'writer', provider: { type: 'local', runtime: 'docker' } } ] // `customTools` is optional and defaults to an empty map }, namespaceProvider: { type: 'create_if_not_exists', namespaceRequest: { name: 'default', deleteOnLastSessionExit: true } }, execution: { mode: 'immediate', runtimeSettings: { ttl: 300000, persistenceMode: { mode: 'hold_after_exit', duration: 5000 } } } }) }) ``` **Response:** ```json theme={null} { "namespace": "default", "sessionId": "session-abc123" } ``` ### Required Fields ```json theme={null} { "id": { "name": "agent-name", "version": "1.1.0", "registrySourceId": { "type": "local" } }, "name": "unique-instance-name", "provider": { "type": "local", "runtime": "docker" } } ``` ### Optional Fields ```json theme={null} { "description": "Custom description visible to other agents", "systemPrompt": "Additional instructions for this agent", "blocking": false, "options": { "EXTRA_USER_PROMPT": { "type": "string", "value": "Your custom instructions here" }, "MAX_ITERATIONS": { "type": "i32", "value": 50 } }, "customToolAccess": ["tool_name_1", "tool_name_2"], "plugins": [ { "type": "close_session_tool" } ] } ``` ### Agent Groups Groups define which agents are aware of each other and can communicate by default. This fragment omits each agent's required `id` and `provider` fields for brevity. ```json theme={null} { "agentGraphRequest": { "agents": [ { "name": "agent1" }, { "name": "agent2" }, { "name": "agent3" }, { "name": "agent4" }, { "name": "agent5" } ], "groups": [ ["agent1", "agent2", "agent3"], ["agent4", "agent5"] ] } } ``` * Agents in the same group can see each other and create threads together * An agent can be in multiple groups * Groups don't start until all `blocking: true` agents have connected ### Custom Tools Definition **Note:** The `customTools` field in `agentGraphRequest` is optional and defaults to an empty object. ```json theme={null} { "agentGraphRequest": { "agents": [], "groups": [], "customTools": { "tool_name": { "transport": { "type": "http", "url": "https://your-app.com/webhook", "signatureHeader": "X-Coral-Signature" }, "description": "What this tool does (shown to agents)", "inputSchema": { "type": "object", "properties": { "param1": { "type": "string", "description": "..." }, "param2": { "type": "number", "description": "..." } }, "required": ["param1"] }, "outputSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" } }, "required": ["success"] } } } } } ``` The server appends `/{sessionId}/{agentName}` to the callback URL and sends tool arguments as the JSON body. It also sends `X-Coral-Namespace`, `X-Coral-SessionId`, and `X-Coral-AgentName` headers. The signature is a lowercase hexadecimal HMAC-SHA256 over the exact body bytes, using `network.customToolSecret` on a self-hosted server. See [callback verification](/guides/integrating-with-your-app#custom-tools). To grant an agent access to a custom tool, add the tool name to the agent's `customToolAccess` array. ### Session Runtime Settings ```json theme={null} { "execution": { "mode": "immediate", "runtimeSettings": { "ttl": 300000, "persistenceMode": { "mode": "hold_after_exit", "duration": 60000 }, "webhooks": { "sessionEnd": { "url": "https://your-app.com/api/session-complete" } } } } } ``` ## Example: Getting output from agents using custom tools This example shows how to create a session with a custom tool that allows an agent to submit a report back to your application. **This is the standard pattern for retrieving results from Coral agents.** ### Application backend: Creating the session ```javascript theme={null} // Store session-to-user mappings const sessionUserMap = new Map(); const response = await fetch('https://api.coralcloud.ai/api/v1/local/session', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' }, body: JSON.stringify({ agentGraphRequest: { agents: [ { id: { name: 'natural-tone-agent', version: '1.1.0', registrySourceId: { type: 'local' } }, name: 'report-writer', provider: { type: 'local', runtime: 'docker' }, customToolAccess: ['submit_report'], options: { EXTRA_USER_PROMPT: { type: 'string', value: 'Analyze Q4 sales data and create a summary report' } } } // ... other agents ], groups: [ ['report-writer'] ], customTools: { submit_report: { transport: { type: 'http', url: 'https://your-app.com/api/coral-webhook', signatureHeader: 'X-Coral-Signature' }, description: 'Submit a completed report to the application', inputSchema: { type: 'object', properties: { title: { type: 'string', description: 'The title of the report' }, content: { type: 'string', description: 'The report content in markdown format' } }, required: ['title', 'content'] }, outputSchema: { type: 'object', properties: { success: { type: 'boolean' }, reportId: { type: 'string' } }, required: ['success'] } } } }, namespaceProvider: { type: 'create_if_not_exists', namespaceRequest: { name: 'default', deleteOnLastSessionExit: true } }, execution: { mode: 'defer' } }) }); if (!response.ok) throw new Error(`Create session failed: ${response.status}`); const { namespace, sessionId } = await response.json(); // Map the session to the current user/tenant sessionUserMap.set(sessionId, currentUserId); // Persist this mapping in a store shared with the callback handler before starting agents. const started = await fetch(`https://api.coralcloud.ai/api/v1/local/session/${encodeURIComponent(namespace)}/${encodeURIComponent(sessionId)}`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' }, body: JSON.stringify({ ttl: 300000 }) }); if (!started.ok) throw new Error(`Start session failed: ${started.status}`); ``` ### Server-side: Handling the custom tool callback Coral POSTs the tool arguments to your callback URL with `/{sessionId}/{agentName}` appended. Verify the raw-body HMAC before trusting the result, and resolve the tenant from your stored job/session mapping. The mapping must be shared with the application backend that created the session; a separate in-memory map in a serverless callback is not sufficient. The [complete Node.js application example](/guides/integrating-with-your-app#complete-application-example) implements deferred startup, signature verification, job-specific callback URLs, and result handling. It is tested against the public server. For Cloud, confirm the deployment's callback verification credentials rather than using the Cloud API key as a signing secret. ## List all sessions **Endpoint:** `GET /api/v1/local/namespace/extended` Returns all sessions across all namespaces. ### Example: ```javascript theme={null} fetch('https://api.coralcloud.ai/api/v1/local/namespace/extended', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }) ``` **Response:** ```json theme={null} [ { "base": { "name": "default", "deleteOnLastSessionExit": true, "annotations": {} }, "sessions": [ { "id": "session-abc123", "namespace": "default", "timestamp": "2026-01-01T00:00:00Z", "status": { "type": "executed", "executionTime": "2026-01-01T00:00:00Z" }, "annotations": {} } ] } ] ``` ## List sessions in namespace **Endpoint:** `GET /api/v1/local/namespace/{namespace}/extended` Returns all sessions in a specific namespace. ### Example: ```javascript theme={null} fetch('https://api.coralcloud.ai/api/v1/local/namespace/default/extended', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }) ``` **Response:** ```json theme={null} { "base": { "name": "default", "deleteOnLastSessionExit": true, "annotations": {} }, "sessions": [ { "id": "session-abc123", "namespace": "default", "timestamp": "2026-01-01T00:00:00Z", "status": { "type": "executed", "executionTime": "2026-01-01T00:00:00Z" }, "annotations": {} } ] } ``` ## Get session state **Endpoint:** `GET /api/v1/local/session/{namespace}/{sessionId}/extended` Returns the complete current state of a session including all agents, threads, and messages. ### Example: ```javascript theme={null} fetch('https://api.coralcloud.ai/api/v1/local/session/default/session-abc123/extended', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }) ``` **Response:** ```json theme={null} { "base": { "id": "session-abc123", "namespace": "default", "timestamp": "2026-01-01T00:00:00Z", "status": { "type": "executed", "executionTime": "2026-01-01T00:00:00Z" }, "annotations": {} }, "agents": [ { "name": "writer", "registryAgentIdentifier": { "name": "natural-tone-agent", "version": "1.1.0", "registrySourceId": { "type": "local" } }, "description": "An agent that writes in natural tone", "links": [ "researcher" ], "status": { "type": "running", "connectionStatus": { "type": "connected", "communicationStatus": { "type": "thinking" } }, "startTime": "2026-01-01T00:00:00Z" } } ], "threads": [ { "id": "thread-123", "name": "Research Discussion", "creatorName": "researcher", "participants": [ "researcher", "writer" ], "state": { "state": "open" }, "messages": [ { "id": "msg-1", "threadId": "thread-123", "senderName": "researcher", "text": "Here are my findings on AI developments", "timestamp": "2026-01-01T00:00:01Z", "mentionNames": [ "writer" ] } ], "timestamp": "2026-01-01T00:00:00Z" } ] } ``` ## Inspecting agent status The session state response includes an `agents` array with the current status of each agent. This is useful for monitoring agent health and debugging. ### Agent State Fields | Field | Type | Description | | - | - | - | | `name` | string | The unique instance name given to this agent in the session | | `registryAgentIdentifier` | object | Reference to the agent's registry entry (name, version, source) | | `status` | object | Runtime status (`waiting`, `running`, `stopped`); a running agent has `connectionStatus`, and a connected agent has `communicationStatus` (`thinking`, `waiting_message`, `sleeping`). | | `description` | string | The agent's description, visible to other agents in the session | | `links` | string\[] | List of other agent names this agent is aware of (from groups) | ### Example: Polling for agent readiness ```javascript theme={null} async function waitForAgentsReady(namespace, sessionId, timeoutMs = 30000) { const startTime = Date.now(); while (Date.now() - startTime < timeoutMs) { const response = await fetch( `https://api.coralcloud.ai/api/v1/local/session/${encodeURIComponent(namespace)}/${encodeURIComponent(sessionId)}/extended`, { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const state = await response.json(); if (!response.ok) throw new Error(`Session read failed: ${response.status}`); const allConnected = state.agents.length > 0 && state.agents.every(agent => agent.status.type === 'running' && agent.status.connectionStatus.type === 'connected' ); if (allConnected) { return state.agents; } await new Promise(resolve => setTimeout(resolve, 1000)); } throw new Error('Timeout waiting for agents to connect'); } ``` ### Example: Checking if agents are idle ```javascript theme={null} async function areAgentsIdle(namespace, sessionId) { const response = await fetch( `https://api.coralcloud.ai/api/v1/local/session/${encodeURIComponent(namespace)}/${encodeURIComponent(sessionId)}/extended`, { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const state = await response.json(); // All agents are idle if they're all waiting for messages if (!response.ok) throw new Error(`Session read failed: ${response.status}`); return state.agents.length > 0 && state.agents.every(agent => agent.status.type === 'running' && agent.status.connectionStatus.type === 'connected' && agent.status.connectionStatus.communicationStatus.type === 'waiting_message' ); } ``` ## Viewing thread contents The session state response includes a `threads` array containing all communication threads and their messages. This enables you to observe agent collaboration in real-time. ### Thread Fields | Field | Type | Description | | - | - | - | | `id` | string | Unique thread identifier | | `name` | string | Thread topic/name | | `creatorName` | string | Name of the agent that created the thread | | `participants` | string\[] | List of agent names participating in the thread | | `state` | object | Either `{ "state": "open" }` or `{ "state": "closed", "summary": "..." }` | | `messages` | array | List of messages in the thread | ### Message Fields | Field | Type | Description | | - | - | - | | `id` | string | Unique message identifier | | `threadId` | string | ID of the thread this message belongs to | | `senderName` | string | Name of the agent that sent the message | | `text` | string | Message content | | `timestamp` | string | UTC ISO-8601 timestamp | | `mentionNames` | string\[] | List of agent names mentioned in this message | ### Example: Getting all messages from a session ```javascript theme={null} async function getSessionMessages(namespace, sessionId) { const response = await fetch( `https://api.coralcloud.ai/api/v1/local/session/${encodeURIComponent(namespace)}/${encodeURIComponent(sessionId)}/extended`, { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const state = await response.json(); // Flatten all messages from all threads, sorted by timestamp const allMessages = state.threads .flatMap(thread => thread.messages.map(msg => ({ ...msg, threadName: thread.name }))) .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp)); return allMessages; } ``` ### Example: Streaming thread updates (polling) This yields each retained message once per generator instance. Set a sufficient `hold_after_exit` duration when creating the session: polling cannot recover messages after the session is removed, and a timestamp is not a unique message cursor. For durable results, use custom tools and store results in your application. ```javascript theme={null} async function* streamThreadUpdates(namespace, sessionId, pollIntervalMs = 2000) { const seen = new Set(); while (true) { const response = await fetch( `https://api.coralcloud.ai/api/v1/local/session/${encodeURIComponent(namespace)}/${encodeURIComponent(sessionId)}/extended`, { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); if (!response.ok) { if (response.status === 404) break; // Session closed throw new Error(`Failed to fetch session: ${response.status}`); } const state = await response.json(); // Find new messages for (const thread of state.threads) { for (const message of thread.messages) { const key = `${message.threadId ?? thread.id}:${message.id}`; if (!seen.has(key)) { seen.add(key); yield { thread, message }; } } } if (state.base.status.type === 'closing') break; await new Promise(resolve => setTimeout(resolve, pollIntervalMs)); } } // Usage for await (const { thread, message } of streamThreadUpdates('default', 'session-abc123')) { console.log(`[${thread.name}] ${message.senderName}: ${message.text}`); } ``` ### Example: Finding threads by participant ```javascript theme={null} async function getThreadsWithAgent(namespace, sessionId, agentName) { const response = await fetch( `https://api.coralcloud.ai/api/v1/local/session/${encodeURIComponent(namespace)}/${encodeURIComponent(sessionId)}/extended`, { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const state = await response.json(); return state.threads.filter(thread => thread.participants.includes(agentName) ); } ``` ## Close a session **Endpoint:** `DELETE /api/v1/local/session/{namespace}/{sessionId}` Closes an active session, cancelling all running agents. ### Example: ```javascript theme={null} fetch('https://api.coralcloud.ai/api/v1/local/session/default/session-abc123', { method: 'DELETE', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }) ``` **Response:** 200 OK (empty body) ## List agents **Endpoint:** `GET /api/v1/registry` Lists all agent types available in the registry. ### Example: ```javascript theme={null} fetch('https://api.coralcloud.ai/api/v1/registry', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }) ``` **Response:** ```json theme={null} [ { "identifier": { "type": "local" }, "timestamp": "2026-01-01T00:00:00Z", "agents": [ { "name": "living-knowledge-agent", "versions": ["0.1.0"] }, { "name": "natural-tone-agent", "versions": ["1.1.0"] } ] } ] ``` ## Inspect an agent **Endpoint:** `GET /api/v1/registry/{source}/{agentName}/{version}` Returns detailed information about a specific agent including its options, capabilities, and configuration schema. **Sources:** * `local` - Agents provided by Coral Cloud * `marketplace` - Community marketplace agents * `linked/{serverName}` - Agents from a linked server ### Example: ```javascript theme={null} fetch('https://api.coralcloud.ai/api/v1/registry/local/natural-tone-agent/1.1.0', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }) ``` **Response:** ```json theme={null} { "registryAgent": { "info": { "description": "An agent that communicates in natural, conversational tone", "capabilities": [ "resources" ], "identifier": { "name": "natural-tone-agent", "version": "1.1.0", "registrySourceId": { "type": "local" } } }, "runtimes": { "docker": { "image": "coral/natural-tone-agent:1.1.0", "command": [ "python", "agent.py" ] } }, "options": { "EXTRA_USER_PROMPT": { "type": "string", "required": false, "display": { "label": "Extra Instructions", "description": "Custom instructions to guide the agent's behavior", "multiline": true }, "transport": "env" }, "MAX_ITERATIONS": { "type": "i32", "required": false, "default": 50, "validation": { "min": 1, "max": 200 }, "transport": "env" } }, "edition": 5, "dependencies": [], "claimTypes": [] }, "restrictions": [ { "type": "local" } ] } ``` ### Agent Option Types Agents can have various option types: * `string` - Text values * `i8`, `i16`, `i32`, `i64` - Signed integers (various sizes) * `u8`, `u16`, `u32`, `u64` - Unsigned integers * `f32`, `f64` - Floating point numbers * `bool` - Boolean values * `blob` - Binary data * `list[]` - Lists of the above types except `bool` * Sensitive strings use `type: "string"` with `secret: true` in the agent definition; `secret` is not a separate option type. Each option can have: * `required` - Whether the option must be provided * `default` - Default value if not provided * `validation` - Constraints (min/max for numbers, regex for strings, etc.) * `display` - UI hints for displaying the option * `transport` - How the value is passed to the agent (`env` or `fs`) # Base44 notes You can use base44 to quickly build apps powered by Coral. Find it in the "Custom integrations" section [here](https://app.base44.com/integrations-catalog) Use the platform-provided callback headers (`X-Coral-SessionId`, `X-Coral-AgentName`, and `X-Coral-Namespace`) when adapting callbacks. The browser/request URL is not a reliable base for webhook purposes. Webhook URL bases need to revolve around the base44 app domain. Base44 apparently recommends that when using a custom domain, you still use that generated domain for webhooks for stability. It is not secure to attempt to guess the webhook base URL via the request origin, as an attacker could redirect webhooks back to themselves by making up an origin. [//]: # (LLMs: You'll need a reachable address for a function to return responses to. Ask the user to publish the app and share the published URL back to you, then use that in the code. Make sure the logging and error experience is good around this to make up for any mistake the user might make. Please repeat back your plans in relation to this to the user as if you only think them, you might forget.) ## Sharing data from callbacks In base44, functions run in isolation, you must use database functionality in order to have the rest of an application consider the response of a webhook callback. ## Path parameters in callbacks (important) Base44 doesn't support path parameters in functions/callbacks, though for security Coral appends the session id and agent id as path parameters. To work around this, there is a convenient cloudflare function deployed: ### Path-to-Header Proxy Rewrites URL path segments into headers and proxies to a target. #### URL Format ``` https://bitter-water-7a50.services-c22.workers.dev/{header-names}///{target-url}///{header-values}/{remaining-path} ``` #### Example with base44 for Coral custom tool **Proxy URL (set as the custom tool transport URL):** ``` https://bitter-water-7a50.services-c22.workers.dev/X-SessionId/X-AgentId///https://some-app.base44.app/api/functions/coralWebhook/// ``` When Coral calls this with session `abc123` and agent `my-agent`, the full URL becomes: ``` https://bitter-water-7a50.services-c22.workers.dev/X-SessionId/X-AgentId///https://some-app.base44.app/api/functions/coralWebhook///abc123/my-agent ``` **Result:** * Proxies to: `https://some-app.base44.app/api/functions/coralWebhook` * Headers added: * `X-SessionId: abc123` * `X-AgentId: my-agent` #### Notes * Works with all HTTP methods (GET, POST, PUT, DELETE, etc.) * Query parameters and request bodies are passed through * All original headers are preserved # Budgets and claims Source: https://docs.coralos.ai/concepts/budgets Limit what agents claim during a session, and see what they reported. Coral Server tracks spending in a session through budgets and claims. An agent reports each billable action as a claim against a claim type declared in its `coral-agent.toml`. The server prices the claim, deducts it from the agent's budget and then the session's, and applies the configured exhaustion policy. Budgets are for accounting purposes and don't inherently move any money. ## Units Budget values and claim costs are integers in **micro cents**. | Amount | Value | | - | - | | USD 1.00 | `100000000` | | USD 0.01 | `1000000` | ## Session budget Set the shared budget on [`SessionRequest`](/api-reference/models/SessionRequest) `budgetSettings`, next to `agentGraphRequest` and `execution`: ```json theme={null} { "budgetSettings": { "budget": 100000000, "exhaustionBehavior": { "type": "kill_session" } } } ``` (request fragment, not a complete session request. The session's exhaustion policy applies when a claim leaves the session budget at or below the policy's `minimum`, which defaults to `0`: | Policy | Effect | | - | - | | `kill_agent` (default) | The claiming agent is told to exit. It is stopped if its claim set `autoKill`, which is the default, or the policy sets `"force": true`. | | `kill_session` | The whole session is stopped after `delay`, 100 ms by default. | | `ignore` | Claims keep being recorded past zero. | ## Agent budgets Each agent in the graph can have its own `budgetSettings`: ```json theme={null} { "budgetSettings": { "budget": 10000000, "claimTypeCosts": { "FETCH_DOCUMENT": 1000000 }, "exhaustionBehavior": { "type": "consume_session" } } } ``` An agent's claims come out of its own budget first. Its exhaustion policy determines what happens next: | Policy | Effect | | - | - | | `consume_session` (default) | The rest of the claim comes out of the session budget, and the session's policy applies. | | `kill` | The agent never draws on the session budget. When its own budget falls to `minimum` or below, it is told to exit, and stopped if the claim set `autoKill` or the policy sets `"force": true`. | `claimTypeCosts` sets the price of each claim type for this session, overriding the cost in the agent's definition. Both budgets default to zero. If an agent makes priced claims, set a budget: with the default policies, its first priced claim stops it. ## Declaring claim types An agent declares its claim types in `coral-agent.toml`. Each claim type belongs to a dependency, which groups the options that power it: ```toml theme={null} [[dependencies]] name = "document-service" options = ["DOCUMENT_API_KEY"] [[claims]] name = "FETCH_DOCUMENT" description = "Fetch one document" dependency = "document-service" cost = 1000000 ``` * Every option a dependency lists must be defined in the agent's `[options]` table. * Claim type names start with a letter or underscore, and contain only letters, digits and underscores. * `cost` is optional. A claim type with no cost in the definition or in `claimTypeCosts` is priced at zero and does not count against any budget. ## Reporting claims An agent reports a claim to `$CORAL_API_URL/api/v1/agent-rpc/claim`, using `CORAL_AGENT_SECRET` as its bearer token. See [the endpoint reference](/api-reference/agent-rpc/submit-an-agent-claim). ```json theme={null} { "claimTypeName": "FETCH_DOCUMENT", "quantity": 1, "additionalDescription": "Fetched document 123", "autoKill": false } ``` * `quantity` multiplies the claim type's cost and defaults to `1`. * `additionalDescription` is optional and truncated to 256 characters. * `autoKill` defaults to `true`. Set it to `false` when the agent should handle exhaustion itself. It must then exit when the response's `shouldExit` is `true`. A policy with `"force": true` still stops it. The response carries a sequential `claimId`, the `requestedAmount` and `fulfilledAmount`, the remaining agent and session budgets, and `shouldExit`. ## Limits of budget enforcement The server checks a claim only after the agent reports it, and records the claim that crosses a limit in full. Work an agent never claims is not counted. Use the session's TTL as a separate limit on how long it can run. ## Observing usage The [extended session state](/api-reference/local/get-extended-session-state) includes the session's `budgetSettings` and `runningBudget`, every claim in `agentClaimReceipts`, and each agent's own budget state. Session state lives in memory, so record claims in your application if you need durable accounting. A `sessionEnd` [webhook](/concepts/sessions#webhooks) with `extendedEndReport` delivers the final state when the session ends. # Multi-Agent Coordination Source: https://docs.coralos.ai/concepts/coordination The thread-based communication model for Coral Agents. Multi-agent coordination in Coral Server is based on a decentralized graph architecture, where agents communicate via a thread-based model. This approach allows agents to collaborate dynamically without a single central controller. ## Thread-Based Communication Agents in a Coral session are organized into threads. A thread is an isolated communication space where agents can exchange messages, share context, and coordinate their actions. * **Thread Creation:** Any agent can create a new thread with a specific topic and invite other agents to participate. * **Message Passing:** Agents send messages to threads. Messages include `text` and optional `mentionNames` to target specific agents. * **Mentions:** Explicitly mentioning another agent in a message will wake it if it's waiting for mentions, alerting it to a specific task or request. ## Collaboration Patterns Coral Server's architecture supports various collaboration patterns: ### Dynamic Graph Patterns In this pattern, the developer does not explicitly plan out every interaction. Agents use their own intelligence to decide which threads to create, who to invite, and what context to share. This is well-suited for complex tasks where the path to a solution isn't fixed. ### Workflow Patterns Developers can also enforce more structured workflows by providing agents with specific instructions and custom tools that act as checkpoints. This pattern is appropriate for algorithmic tasks where sub-problems are well-defined in advance. ## Coordination Tools Every agent is given a standard set of MCP tools for coordination (tool IDs are prefixed with `coral_`): | Tool | Purpose | | :- | :- | | `coral_create_thread` | Creates a new thread with a topic and initial participants. | | `coral_send_message` | Sends a message to a thread and mentions other agents. | | `coral_wait_for_mention` | Suspends agent execution until it is mentioned in any thread. | | `coral_wait_for_message` | Suspends execution until a message matching certain filters is received. | | `coral_wait_for_agent` | Suspends until a message arrives from a specific agent. | | `coral_add_participant` | Adds another agent to an existing thread. | | `coral_remove_participant` | Removes a participant from a thread. | | `coral_close_thread` | Closes a thread when work is complete. | ## Why Graph-Based? Traditional multi-agent systems often use a hierarchical approach, which can lead to bottlenecks and overhead. Coral's graph-based design enables direct agent-to-agent communication, which results in: * **Higher Throughput:** Multiple agents can run concurrently without blocking. * **Scalability:** The system scales by adding more intelligent agents rather than making models larger. * **Safer and More Predictable Systems:** Specialized agents handle smaller, well-defined responsibilities. For more information on the architecture, see [Coral Server](/about). # Coral Console Source: https://docs.coralos.ai/concepts/coral-console Coral Console is a visual interface built into Coral Server, making it easier to inspect, test, and debug agent behaviour during development. Coral Console is accessible locally when Coral Server is running. By default, it is available at: [http://localhost:5555/ui/console](http://localhost:5555/ui/console) Use it to: * View available agents in your Coral Server * Create and manage sessions * Trigger test prompts and inspect agent responses * Monitor real-time logs and thread history It is built into Coral Server. Coral Console simply makes it easier to prototype and debug agent behaviour during development. Thread message composer while acting as the operator agent ### What can you do with Coral Console? Use Coral Console to configure and launch sessions on Coral Server with selected agents * Send messages between agents in shared threads to coordinate behaviour * Inspect agent-to-agent messages in threaded conversations Coral Console displays the real-time status of every agent: 1. Disconnected (not connected, and not orchestrated) 2. Connecting (was part of an agent graph and waiting for connection) 3. Waiting (connected and waiting for a message) 4. Thinking (connected but not waiting for a message) 5. Stopped (process exited) This helps devs monitor which agents are online and responsive during execution and spot issues instantly. Agent overview showing the operator's status and thread membership ### What a Real Interaction Looks Like? Thread history showing a message from operator and the echo agent's reply Here's a real example of how agents collaborate inside a session. The operator sends a test message → The built-in echo agent replies **nice message!** → All activity is logged in real time. This debugging example uses the built-in `puppet` agent, named `operator`, and `echo`, configured to stop after one reply. No language model is needed. This would clarify what Coral Console helps you observe. ### Key Components View agents available in your Coral Server Every task lives in a **Communication Thread** a persistent conversation across agents Choose agents, configure their options, and set session budgets and TTL Attach input tools or test agent prompts from the UI Real-time logs from running agents > Agents run independently and only respond when triggered. Coral Console visualises message flow and thread activity powered by Coral Server. ### Who is it for ? * Developers building, testing and debugging Coral Agents * Framework creators testing Coral compatibility * Researchers and tinkerers exploring multi-agent design ### How it fits in your workflow? Coral Console helps during the prototyping and debugging phase. You don’t need to write custom coordination logic or scripts; just define your agents, wire them together, and test the interaction in real-time. ### Get Started Coral Console is enabled by default in Coral Server. Once the server is running, simply visit: [http://localhost:5555/ui/console](http://localhost:5555/ui/console) For more details on server configuration, check the [Coral Server README](https://github.com/Coral-Protocol/coral-server). # Marketplace Source: https://docs.coralos.ai/concepts/marketplace Discover, publish, and verify agents. How the marketplace integration works. # Marketplace Integration The Coral marketplace lets servers discover agents, and lets agent authors publish their agents with optional pricing metadata and identity attestation. In v1.5.0, the marketplace integration is focused on discovery and metadata. Remote execution and payments are disabled by default (see [Status](#status-v1-5-0)). ## Enable marketplace discovery on your server Marketplace-backed registry entries are provided by the `MarketplaceAgentRegistrySource`. * Config entry: `registry.enableMarketplaceAgentRegistrySource` (default: `false`) * Source of truth: `RegistryConfig.kt` and `MarketplaceAgentRegistrySource.kt` ```toml config.toml theme={null} [registry] enableMarketplaceAgentRegistrySource = true ``` When enabled, Coral Server adds a marketplace source to the local `AgentRegistry` on startup. You can list available agents grouped by registry source via the API: ```bash theme={null} curl -H "Authorization: Bearer $CORAL_TOKEN" \ http://localhost:5555/api/v1/registry | jq ``` ## Publishing agents for discovery Agent authors publish with a standard [`coral-agent.toml`](/reference/agent) (edition 5). For marketplace visibility, add pricing metadata under `[marketplace.pricing]`. This metadata is validated during load. Adding the table does not publish an agent or upload its Docker image; those are separate marketplace and container-registry operations. ```toml coral-agent.toml (excerpt) theme={null} edition = 5 [agent] name = "natural-tone-agent" version = "1.1.0" description = "An agent that writes in natural, conversational tone" summary = "Natural tone writing agent" readme = "An agent for writing natural language content." license = { type = "spdx", expression = "MIT" } [marketplace.pricing] description = "A full markdown description of how the agent is priced" currency = "USD" [marketplace.pricing.recommendations] min = 0.01 max = 1.50 ``` Validation limits and field requirements are enforced in the marketplace pricing models (see `RegistryAgentMarketplacePricing` in `RegistryAgent.kt`), as well as core agent validation (name pattern, version semver, description lengths, etc.). If values are invalid, the server rejects the agent with a readable error. ## Identity & attestation (overview) Marketplace entries can include identity hints (e.g., ERC‑8004 wallet and HTTPS endpoints) to support future remote execution attestation. * Types and constraints are defined in `RegistryAgentMarketplaceSettings.kt` under `marketplace.identities.erc8004`. * Endpoints must use HTTPS, names must match the required pattern, and wallet addresses are validated (Base58). Attestation and remote rental are under active development. See Status for current limitations. ## Using marketplace agents in sessions Even when discovered from the marketplace, agents can still be launched locally on your server (using the image you control). In your `SessionRequest`, reference the source type: ```json theme={null} { "agentGraphRequest": { "agents": [ { "id": { "name": "natural-tone-agent", "version": "1.1.0", "registrySourceId": { "type": "marketplace" } }, "name": "writer", "provider": { "type": "local", "runtime": "docker" } } ], "customTools": {} } } ``` The Registry API (`/api/v1/registry/...`) exposes marketplace items side by side with local ones, including option schemas and marketplace metadata. ## Status (v1.5.0) * Remote providers/payments are disabled. Only `provider.type = "local"` is supported for execution on v1.5.0. * Pricing metadata does not set session budgets. See [Budgets and claims](/concepts/budgets) for local usage accounting. * Use the marketplace today primarily for discovery and metadata; execution should be local. See also: * [Budgets and claims](/concepts/budgets) * [Security](/configuration/security) * [MCP Integration](/concepts/mcp) # MCP Integration Source: https://docs.coralos.ai/concepts/mcp Coral Server implements the Model Context Protocol (MCP) to enable seamless integration between agents, servers, and applications. Coral Server integrates the [MCP](https://modelcontextprotocol.io/) protocol to let AI agents collaborate. Each orchestrated agent receives its own MCP endpoint. Streamable HTTP is the default transport; legacy SSE is also supported. ## How Coral Server uses MCP When an agent is orchestrated, `CORAL_CONNECTION_URL` contains its MCP endpoint and a unique agent secret in the URL path. Connect using that exact URL and do not log it. Agent secrets also authenticate agent RPC requests; application REST requests use a server `auth.keys` bearer token. ### Standard Tools Coral Server provides every agent with a default set of MCP tools for coordination (tool names are prefixed with `coral_`): * `coral_create_thread` — Create a new communication thread in the current session. * `coral_send_message` — Send a message to a specific thread (supports mentions). * `coral_wait_for_message` — Wait for the next message matching filters. * `coral_wait_for_mention` — Wait until the agent is mentioned. * `coral_wait_for_agent` — Wait for the next message from a specific agent. * `coral_add_participant` / `coral_remove_participant` — Manage thread participants. * `coral_close_thread` — Close a thread when a topic is complete. * `coral_close_session` — Optionally close the session (if enabled by plugins). ### Resources Coral Server exposes session‑related information through MCP resources: * **Instructions** (`coral://instruction`): Markdown guidance compiled from snippets describing how to use messaging, mentions, and waiting tools effectively. * **State** (`coral://state`): An agent‑visible snapshot of the current session state (e.g., active threads and recent messages). For a detailed breakdown of what each resource contains and how they're injected into agents, see [Resources](/features/resources). ## Integrating with your Application If you're building an application, you can integrate with Coral agents by: 1. **Providing Custom Tools:** Define your own MCP tools and include them in the `agentGraphRequest.customTools` when creating a session. Coral Server will forward tool calls from agents to your specified HTTP endpoints. 2. **Debugging with Puppet:** During development, use the Puppet API to create threads, send messages, and manage participants on behalf of an agent. Use custom tools for application input and output. ### Tool Definition Example This fragment defines a custom tool. Include it alongside the session's `agents` array and grant access with `customToolAccess: ["query_database"]` on each agent that needs it: ```json theme={null} { "agentGraphRequest": { "customTools": { "query_database": { "transport": { "type": "http", "url": "https://your-api.com/query" }, "description": "Query the company's SQL database", "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] }, "outputSchema": { "type": "object" } } } } } ``` For more details on integrating with your application, see [Integrating with your App](/guides/integrating-with-your-app). # LLM proxying Source: https://docs.coralos.ai/concepts/proxy LLM proxying is a process where agents send requests to an intermediate server rather than directly to an LLM provider. The intermediate server analyzes LLM requests and responses to provide additional features to agents and applications. CoralOS has two distinct LLM proxies, for Coral Cloud and Coral Server. With your own Coral Server, you can configure provider keys directly or use the Coral Cloud LLM proxy as a convenience option. # Coral Server The Coral server also offers an LLM proxy to the agents that it runs. Passing LLM traffic through the Coral server provides a number of benefits, such as: * Automatic agent telemetry collection * Eliminating the agent's need to hold LLM provider keys * Agent cost control * Agent model and provider substitution * LLM provider fallbacks * LLM provider key cycling Read more about how to configure agents to use the Coral server LLM proxy [here](/reference/agent/tables/llm#llm-proxies) and how to configure LLM proxies on the Coral server [here](/reference/server/llm-proxy). ## Your own LLM provider keys Configure providers such as OpenAI, Anthropic, or DeepSeek directly in your server's `config.toml`. Coral Server holds the provider keys and routes each agent's model requests to a matching provider. ```toml theme={null} [[llm-proxy.providers]] name = "OpenAI" format.type = "OpenAI" api_key = "YOUR_OPENAI_API_KEY" base_url = "https://api.openai.com" models = ["gpt-4.1-mini", "gpt-5-mini"] ``` Load the file using `CONFIG_FILE_PATH`. See [provider configuration](/reference/server/llm-proxy#providers) for an Anthropic example and [base URL composition](/reference/types/llm-proxy-provider-config#base_url) when using a different SDK or compatible endpoint. # Coral Cloud The Coral Cloud LLM proxy is an optional upstream provider for your self-hosted Coral Server. A Cloud API key automatically configures supported providers and models, with model usage charged through Coral Cloud. ```toml theme={null} [cloud] api_key = "my Coral Cloud API key" ``` Your server, console, and agent sessions still run on your own infrastructure. Using this LLM proxy does not require using the Cloud-hosted server or console. See [Cloud configuration](/reference/server/cloud). # Sessions Source: https://docs.coralos.ai/concepts/sessions In CoralOS, a session represents a single, self-contained context for a multi-agent interaction. Sessions represent a single, self-contained context for a multi-agent interaction. You can think of a session as a **workspace** or **conversation instance** dedicated to a particular task or user request. It encompasses the agents involved, the messages they exchange, and any temporary state or budget allocated for each agent in that session. ## Namespaces Sessions are organized into **Namespaces**. A namespace is a container for sessions, often used to separate data between different users, applications, or environments. * **Organisation:** Agent communication is scoped to a session. Namespaces organise sessions; they are not per-tenant API credentials. A server `auth.keys` token can access all namespaces, so your application must enforce user and tenant access. * **Persistence:** Namespaces can be configured to persist even after all sessions within them have ended, or to be deleted automatically on the last session exit. ## Session Lifecycle 1. **Creation:** Create a session via `POST /api/v1/local/session` with a `SessionRequest` body. Namespaces are handled by `namespaceProvider` in the request (e.g., `CreateIfNotExists` or `UseExisting`). The response contains a `SessionIdentifier` (`sessionId`, `namespace`). 2. **Launching:** Agents are orchestrated (e.g., via Docker or local executables) and connect to the Coral Server's MCP endpoints. 3. **Active:** Agents collaborate using the thread-based communication model. 4. **Closing:** The session can be closed manually, or it will close automatically when its Time To Live (TTL) expires. 5. **Persistence:** After closing, a session can be held for a specified duration based on `SessionPersistenceMode`. ## Persistence Modes Coral Server supports different session persistence modes (set on `SessionRuntimeSettings.persistenceMode`) to control how long a session remains accessible after it ends. Use `SessionRuntimeSettings.ttl` to bound overall lifetime. * **SessionPersistenceMode.None:** The session is deleted immediately after all agents have finished. * **SessionPersistenceMode.HoldAfterExit:** The session is kept for a fixed duration after its agents exit. * **SessionPersistenceMode.MinimumTime:** The session will exist for at least a specified total duration (including runtime). These modes retain state **in memory**. They do not store sessions durably or restore them after a server restart. Retained sessions report `status.type = "closing"`; once removed, reads return 404. Export results to your own storage through custom tools or an end-report webhook. For immediate execution, settings belong under `execution.runtimeSettings`: ```json theme={null} { "execution": { "mode": "immediate", "runtimeSettings": { "ttl": 300000, "persistenceMode": { "mode": "hold_after_exit", "duration": 60000 } } } } ``` The default TTL is unset and persistence defaults to `none`. Set both deliberately. To store a session-to-job mapping before agents can call your application, create with `execution: { "mode": "defer" }`, persist the returned identifier, then POST runtime settings directly to `/api/v1/local/session/{namespace}/{sessionId}`. ## Webhooks Sessions can be configured with webhooks to notify your application of lifecycle events. For example, set `webhooks.sessionEnd` in `SessionRuntimeSettings` to receive a `SessionEndReport` when the session closes. If `extendedEndReport` is enabled, the report includes the extended session state. ## How can I create a session? Sessions can be created through the [Coral Console interface](/concepts/coral-console) or [programmatically via the REST API](/cloud/using-api). For direct API usage, call `POST /api/v1/local/session` with a `SessionRequest`. *** For more details on the session API, see the [API Reference](/cloud/using-api). # Threads Source: https://docs.coralos.ai/concepts/threads The messaging system in CoralOS, where agents communicate and collaborate on tasks. In Coral, a **thread** is a structured communication context dedicated to a specific purpose, typically a task, topic, or interaction. You can think of it as a group chat for a particular objective, where the participants are primarily AI agents. ## How threads fit into sessions * Threads live inside a [Session](/concepts/sessions). A session can have many threads. * Threads are created and managed by agents using Coral’s standard MCP tools. * Participation is explicit: an agent must be a participant of a thread to post or receive messages from it. See also: [Multi‑Agent Coordination](/concepts/coordination) for higher‑level collaboration patterns over threads. ## Creating and using threads (MCP tools) Every agent gets a standard set of MCP tools for thread coordination (tool IDs are prefixed with `coral_`): * `coral_create_thread` — Create a new thread with a topic and initial participants * `coral_add_participant` / `coral_remove_participant` — Manage who can see and post in the thread * `coral_send_message` — Post a message to a thread, optionally mentioning other agents * `coral_close_thread` — Close a thread when work is complete * `coral_wait_for_mention` — Suspend until the agent is mentioned in any thread * `coral_wait_for_message` — Suspend until a message matching filters arrives * `coral_wait_for_agent` — Suspend until a message arrives from a specific agent For details about the tools and resources, see [MCP Integration](/concepts/mcp). ## What information is in a thread? Each thread contains metadata and a list of messages. When you query the server state, you’ll see fields like (exact property names): * `id` — Unique thread identifier * `name` — Thread topic/name * `creatorName` — The agent that created the thread * `participants` — Agents that currently participate in the thread * `state` — `SessionThreadState` (`Open` or `Closed`). `Closed` includes a `summary` and `timestamp`. * `messages` — Array of messages in the thread Each message contains: * `id` — Unique message identifier * `threadId` — The thread this message belongs to * `senderName` — The agent that sent the message * `text` — Message content * `timestamp` — `Instant` (UTC) timestamp * `mentionNames` — Agents explicitly mentioned in the message You can retrieve this data via the API. See the examples in the [Cloud API reference](/cloud/using-api#viewing-thread-contents). ## Best practices * Model independent sub‑tasks as separate threads to keep message histories focused and small. * Use `mentionNames` to route work to the right agent(s) and to wake waiting agents deterministically. * Prefer concise messages and link to artifacts by reference (e.g., resource URIs) to reduce context size. ## Related topics * [Sessions](/concepts/sessions) * [Multi‑Agent Coordination](/concepts/coordination) * [MCP Integration](/concepts/mcp) # Environment Variables Reference Source: https://docs.coralos.ai/configuration/environment-variables Configure Coral Server and agents using environment variables. Coral Server and agents can be configured through environment variables. Server configuration lives in `config.toml`; there is no separate `registry.toml`. ## Coral Server Configuration The Coral Server reads configuration from a TOML file and also supports overriding any config key via environment variables (through Hoplite's environment source). One explicit environment variable is supported for locating the primary config file: | Variable | Description | Default | | :- | :- | :- | | `CONFIG_FILE_PATH` | Optional path to a `config.toml` file to load on startup. A specified file must exist. | No disk file is loaded unless set; code defaults and an optional bundled `/config.toml` are also available. | Common configuration keys and their defaults (set in code): * `network.bindAddress`: `0.0.0.0` * `network.bindPort`: `5555` * `logging.logFilesDirectory`: `~/.coral/logs` * `logging.logFileName`: `server.log` (inside `logging.logFilesDirectory`) Overriding via environment variables: * Use a **double underscore between table and field**, and a single underscore between words within a field: `NETWORK__BIND_PORT=5555` maps to `network.bindPort`. `NETWORK_BIND_PORT` does not override that setting. (Hoplite does the mapping) * For the standard server build, command-line settings override environment settings, which override the file supplied through `CONFIG_FILE_PATH`. * You can instead mount a complete `config.toml` and set `CONFIG_FILE_PATH`. *Note:* There are no fixed server variables like `CORAL_SERVER_BIND_ADDRESS`, `CORAL_SERVER_BIND_PORT`, `REGISTRY_FILE_PATH`, or `CORAL_DATABASE_PATH` in v1.5.0; use the config keys above or `CONFIG_FILE_PATH`. ## Agent Configuration When Coral Server orchestrates an agent (e.g., via Docker), it passes several environment variables to the agent process. These are used to provide the agent with session-specific context and credentials. ### Standard Agent Variables | Variable | Description | | :- | :- | | `CORAL_CONNECTION_URL` | Connection URL for the agent to reach the server's MCP endpoint (SSE or Streamable HTTP), resolved per runtime and address context. | | `CORAL_AGENT_ID` | The unique agent name within the session. | | `CORAL_AGENT_SECRET` | Secret used by the agent to authenticate with the MCP server. | | `CORAL_SESSION_ID` | The session ID the agent belongs to. | | `CORAL_API_URL` | Base URL for the Coral API, resolved per runtime/address context. | | `CORAL_RUNTIME_ID` | Runtime type identifier (e.g., `docker`, `executable`). | | `CORAL_PROMPT_SYSTEM` | Optional system prompt override, when defined for the agent. | | `CORAL_PROXY_URL_` | Base URL for a resolved proxy request named ``. | | `CORAL_PROXY_FORMAT_` | Format for that proxy request. | | `CORAL_PROXY_MODEL_` | Model selected for that proxy request. | *Notes:* * `CORAL_SERVER_URL`, `CORAL_AGENT_NAME`, `CORAL_NAMESPACE`, `CORAL_SEND_CLAIMS`, and `CORAL_REMOTE_AGENT` are not set for local Docker/executable agents in public Server 1.5.0. Use `CORAL_API_URL`, `CORAL_AGENT_ID`, and application session metadata as appropriate. ### Agent-Specific Options Custom options defined in the `coral-agent.toml` for an agent are also passed as environment variables by default (if `transport = "env"`). For example, if an agent has an option named `OPENAI_API_KEY`: ```toml theme={null} [options.OPENAI_API_KEY] type = "string" required = true ``` The agent will receive an environment variable named `OPENAI_API_KEY` containing the value provided by the user. ## Tips for Docker When running Coral Server in Docker, prefer mounting a config file and pointing the server to it: ```bash theme={null} docker run \ -p 5555:5555 \ -v $(pwd)/config.toml:/config.toml \ -e CONFIG_FILE_PATH=/config.toml \ ghcr.io/coral-protocol/coral-server:latest ``` For example, add `-e NETWORK__BIND_PORT=5555` to override the configured port. Environment names follow the same double-underscore mapping across deployments. # Security Source: https://docs.coralos.ai/configuration/security Auth keys, request signing, and agent secrets in Coral Server 1.5.0. This page explains how authentication and request signing work in Coral Server, and how agent secrets are handled at runtime. # Authentication keys (server API) * Source of truth: `AuthConfig.kt` * Configuration source: `config.toml` (via Hoplite in `ConfigModule.kt`) Application REST APIs accept server auth keys as bearer tokens. Console also uses a session cookie; WebSocket routes have their own token/cookie connection forms. A server auth key grants access across namespaces, so enforce end-user authorization in your application. ```toml theme={null} # config.toml (excerpt) [auth] # A list of accepted bearer tokens for server APIs keys = ["dev-token-123", "another-token"] ``` Use one of these tokens in the `Authorization: Bearer ...` header when calling APIs such as `/api/v1/local/session` or `/api/v1/registry`. Keep tokens secret. Do not commit them to source control. # Request signing for webhooks and custom tools * Source of truth: `NetworkConfig.kt` (`webhookSecret`, `customToolSecret`), `LocalSessionManager.handleSessionClose`, `GraphAgentToolTransport.Http`, and `HttpSignatureUtils.kt` Coral signs JSON payloads for server‑initiated webhooks (e.g., `sessionEnd`) and for HTTP‑based custom tool requests. Verify signatures on your server to prevent spoofing. ```toml theme={null} # config.toml (excerpt) [network] # Used to sign webhook payloads (e.g., sessionEnd) webhookSecret = "CHANGE-ME-32-CHARS" # Used to sign custom tool callouts to your HTTP endpoints customToolSecret = "CHANGE-ME-ANOTHER-SECRET" ``` Verification pattern (default header and algorithm): ```text theme={null} X-Coral-Signature: lowercase_hex(HMAC-SHA256(secret, rawBodyBytes)) ``` Use `webhookSecret` for session-end reports and `customToolSecret` for custom tool calls. Signatures cover only the body, not path parameters or identity headers; correlate callbacks through application-owned job state. The default signature header is `X-Coral-Signature`. For HTTP custom tools, you may override the header name via the transport’s `signatureHeader` option; otherwise the default is used. See the examples in [Integrating with your app](/guides/integrating-with-your-app#custom-tools). Always verify request signatures in production. # SessionAgentSecret (agent → server) * Source of truth: `SessionAgent.kt` and `LocalSessionManager.issueAgentSecret` For each agent instance in a session, Coral issues a unique `SessionAgentSecret`. This secret authenticates the agent when connecting to the MCP server (Streamable HTTP or legacy SSE). Properties: * Random per agent instance * Only valid for the lifetime of the session * Revoked automatically when the session ends Best practices for agent authors: * Read `CORAL_AGENT_SECRET` from the environment provided by the orchestrator * Use the supplied MCP URL; use the secret as a bearer token only for agent RPC endpoints * Do not log or transmit the secret elsewhere Related env vars (set by the orchestrator): | Variable | Purpose | | :- | :- | | `CORAL_CONNECTION_URL` | MCP transport URL to connect to | | `CORAL_AGENT_ID` | Unique name of this agent instance in the session | | `CORAL_AGENT_SECRET` | Secret used to authenticate to Coral’s MCP endpoints | | `CORAL_SESSION_ID` | Session identifier | | `CORAL_API_URL` | Coral Server REST API base URL | # CORS and CSRF considerations The server’s CORS policy is controlled by `NetworkConfig.allowAnyHost` (default: `false`). ```toml theme={null} [network] allowAnyHost = false # set true only for local development ``` Set `allowAnyHost = false` in production and explicitly configure your reverse proxy/frontend to call Coral from trusted origins. # Checklist * [ ] Use strong random `auth.keys`, rotate regularly * [ ] Set `webhookSecret` and `customToolSecret` to strong values * [ ] Verify webhook signatures in your app * [ ] Never log `CORAL_AGENT_SECRET` * [ ] Keep `allowAnyHost = false` in production The [runnable application example](/guides/integrating-with-your-app#complete-application-example) verifies the raw-body signature and rejects tampered payloads. # Resources Source: https://docs.coralos.ai/features/resources How Coral gives agents live context about their session and collaboration rules. Coral Server exposes two MCP [resources](https://modelcontextprotocol.io/docs/concepts/resources) to every agent in a session. You can think of resources as briefing documents that tell the agent what tools are available, who else is in the session, and what's happened so far. Both are dynamic: their content updates as the session evolves. In most cases, we recommend injecting both resources into the agent's system prompt. Manual `readResource` calls are still useful, but mainly when your runtime needs programmatic access to the resource contents. ## The Two Resources | Resource URI | What it provides | Format | | :- | :- | :- | | `coral://instruction` | How to use Coral's tools and messaging patterns | Markdown | | `coral://state` | The agent's visible slice of the session: other agents, threads, and messages | Markdown with embedded JSON | ### Instructions (`coral://instruction`) The instruction resource is dynamically compiled from **snippets**, short markdown sections that explain specific capabilities. Snippets are tied to tools: when an agent has access to a tool, the corresponding instructions are automatically included. Agents with different tool sets get different instructions. An agent without wait tools won't see documentation about waiting. | Snippet | Included when | Covers | | :- | :- | :- | | `BASE` | Always | What Coral is, that messaging tools are the only way to communicate with other agents | | `MESSAGING` | Agent has thread/message tools | Thread lifecycle, participants, sending messages | | `MENTIONS` | Agent can send mentioned messages or wait on mentions | How @‑mentions work and when to use them | | `WAITING` | Agent has any wait tool | The three wait tools (`wait_for_message`, `wait_for_agent`, `wait_for_mention`) and their behaviour | Instructions are assembled at read time. If a tool is added to an agent mid‑session via a plugin, the corresponding instructions appear on the next read. ### State (`coral://state`) The state resource renders the session from this agent's perspective. It is rebuilt on every read, so it always reflects the current moment. It always includes a general section, and may additionally include agent and thread sections when there is visible data: * **General:** The agent's own name and the current timestamp. * **Agents:** A JSON array of linked agents with fields like `agentName`, `agentDescription`, `agentConnected`, `agentWaiting`, `agentRunning`, and `agentStartTime`. * **Threads:** A JSON array of threads the agent participates in, including each thread's name, participants, open/closed state, and either message history or a closure summary. ````markdown theme={null} # General You are an agent named researcher. The current UNIX time is 1749484800000 (ISO-8601: 2025-06-09T16:00:00Z). # Agents You collaborate with 1 other agents, described below: Consider that they have different contexts and instructions and don't necessarily know what you know unless you tell them. ```json [{ "agentName": "writer", "agentDescription": "Drafts and edits content", "agentConnected": true, "agentWaiting": false, "agentSleeping": false, "agentRunning": true, "agentStartTime": "2025-06-09T15:58:00Z" }] ``` # Threads and messages You have access to the following threads and their messages: ```json [{ "threadId": "t-001", "threadName": "research-findings", "owningAgentName": "researcher", "participatingAgents": ["researcher", "writer"], "state": "open", "messages": [{ "messageText": "Here are the key findings from the analysis.", "sendingAgentName": "researcher", "messageTimestamp": "2025-06-09T15:59:30Z", "mentionAgentNames": ["writer"] }] }] ``` ```` State is scoped to the reading agent. An agent only sees threads it participates in and agents it is linked to, never the full session. ## How Resources Reach the Agent Resources are served via the standard MCP resource protocol, so any MCP client can read them directly. Coral also supports **system prompt injection**, so the agent doesn't need to fetch resources itself. ```mermaid theme={null} flowchart TD R1["coral://instruction"] --> MCP["MCP Resource Protocol"] R2["coral://state"] --> MCP MCP --> Manual["Manual readResource()"] MCP --> Auto["System Prompt Injection"] Manual --> Ctx["Agent Context"] Auto --> Ctx ``` ### System prompt injection This is the recommended approach. Rather than reading resources in code, you can embed resource placeholders directly in your agent's system prompt. At runtime, the placeholders are resolved and replaced with the actual resource content before the LLM sees the prompt. This is how our reference agents work. A simple example from the template agent looks like this: ```python theme={null} SYSTEM_PROMPT_TEMPLATE = """{custom_prompt} -- Start of messages and status -- coral://instruction coral://state -- End of messages and status -- """ ``` Each `` tag is replaced with the current content of that resource. In Coral's reference runtimes, resources are re-resolved each loop iteration, so the agent sees new threads, messages, and agent status changes as they happen. How this works depends on your runtime: * **Prototype runtime:** The default system prompt already includes both resource placeholders, and Coral resolves them automatically at runtime. See [Prototype Runtime](/reference/agent/tables/runtimes/prototype) for configuration. * **Custom runtimes:** You handle injection in the way that fits your framework. In Kotlin our reference agents use `injectedWithMcpResources()`. In Rust they use `CompletionEvaluatedPrompt::all_resources()`. ### Reading resources manually Any agent connected via MCP can call `readResource` at any time. This is useful when your runtime needs programmatic access to the resource contents instead of prompt-level injection. ```python theme={null} instructions = mcp_client.read_resource("coral://instruction") state = mcp_client.read_resource("coral://state") ``` `CORAL_STATE_RESOURCE_URI` and `CORAL_INSTRUCTION_RESOURCE_URI` are named constants for agent-definition string references, not environment variables injected into agents. See [PotentialStringReference](/reference/types/potential-string-reference) for details. ## What's Coming: Proxy‑Level Injection Coral Server includes an LLM proxy that agents can route their API calls through for credential management and token tracking. A planned enhancement will have the proxy automatically inject resource content into LLM requests. This would remove the need to read resources or template system prompts entirely. Proxy‑level injection is not yet available. For now, use manual `readResource` calls or system prompt injection as described above. # Telemetry Source: https://docs.coralos.ai/features/telemetry Observe public Coral Server sessions, logs, and LLM proxy usage. Public Coral Server 1.5.0 exposes session state, logs, and session events. It does **not** expose the historical `POST /api/v1/telemetry/{sessionId}` or per-message telemetry GET endpoints. Those paths return 404. A Console screenshot or feature from another release does not establish an API contract for the server you are running. ## What is available * `GET /api/v1/local/session/{namespace}/{sessionId}/extended` returns agent status, threads, messages, and agent budget state. * The LLM proxy emits `llm_proxy_call` session events with the agent name, model, provider request name, HTTP status, and input/output token usage when the provider supplies it. * Session events include runtime start/stop, thread messages, Docker container lifecycle, and budget claims. * Agent stdout/stderr and server diagnostics are available through the logging system and Console. Configure retention and levels in [Logging](/reference/server/logging). These interfaces observe requests that pass through Coral. Calls an agent makes directly to an external LLM provider are outside the Coral proxy's visibility. ## Application results and durable records Use [custom tools](/guides/integrating-with-your-app#custom-tools) for application results. Configure an [end-report webhook](/concepts/sessions#webhooks) to export session state, and store records in your own application. Session retention and the log replay buffer are bounded; they are not durable telemetry storage. Console capabilities depend on the Console release paired with your server. See [Console configuration](/reference/server/console) and [Debugging](/guides/debugging). # Coralizer CLI Guide Source: https://docs.coralos.ai/guides/coralizer The Coralizer CLI tool helps you turn any tool or MCP server into a Coralized agent. To turn MCP servers into a Coral agent, we now recommend asking a coding agent such as Codex or Claude Code to build one, using the [Koog agent template](https://github.com/Coral-Protocol/coral-koog-agent) as a reference. You get a Koog agent you can extend, instead of a generated LangChain or coral-rs project. See [Converting an MCP Server](#converting-an-mcp-server) for an example prompt. Coralizer's `link` command is still a quick way to make a local agent available to your server. The `coralizer` CLI is a powerful tool designed to simplify the process of creating, configuring, and registering agents for the Coral OS. It provides several commands to help you manage your agents and their dependencies. ## Installation Coralizer is published on npm as `@coral-protocol/coralizer`. Run it without installing, which needs Node.js: ```bash theme={null} npx @coral-protocol/coralizer@latest --help ``` Or install it globally to use the `coralizer` command directly: ```bash theme={null} npm install -g @coral-protocol/coralizer coralizer --help ``` To build from source instead, use `cargo install --git https://github.com/Coral-Protocol/coralizer`. ## Core Commands ### `mcp` Scaffold a Coral agent project from one or more MCP servers. Generates the project structure and a `coral-agent.toml` with discovered options. Usage: ```bash theme={null} coralizer mcp [-f|--framework langchain|coral-rs] [-n|--name ] ``` Example: ```bash theme={null} coralizer mcp ./my-agent ./mcp-servers.json -f langchain -n my-mcp-agent ``` ### `link` Create a versioned symlink for the current agent (directory containing `coral-agent.toml`) into `~/.coral/agents//`. This makes the agent discoverable by Coral Server's local registry. ```bash theme={null} coralizer link . ``` ### `unlink` Safely remove the versioned symlink for the current agent. ```bash theme={null} coralizer unlink . ``` ### `updeletelink` Remove all version links for an agent except the latest. ```bash theme={null} coralizer updeletelink . ``` ## Using Templates Coralizer supports multiple frameworks via templates. These include the basic structure for an agent and its `coral-agent.toml` file. * Python: `langchain` * Rust: `coral-rs` ## Common Workflows ### Converting an MCP Server Recommended: instead of running `coralizer mcp`, give a coding agent such as Codex or Claude Code a prompt like this: ```text theme={null} Build a Coral agent around these MCP servers: . Use https://github.com/Coral-Protocol/coral-koog-agent as the reference for the project structure, coral-agent.toml, options, and the connection to Coral. Follow https://docs.coralos.ai/guides/writing-agents. work with me to figure out how to idiomatically define this agent to take the related responsibilities, and define the options to add appropriate flexibility and reusability. Consider the amount of responsibility and information the agent is likely to deal take, and whether it could be optimal to define more agents. ``` If you have an existing MCP server, you can quickly scaffold a Coral agent using the `mcp` command. 1. Prepare an MCP servers JSON (see the Coralizer repo for format) describing your MCP server(s). 2. Generate the agent project: ```bash theme={null} coralizer mcp ./my-agent ./mcp-servers.json -f langchain -n my-agent ``` 3. Configure the agent: Edit the generated `coral-agent.toml` to set your agent's name, version, runtimes, and options. 4. Make it discoverable by the local server: ```bash theme={null} cd ./my-agent coralizer link . ``` ### Building a New Agent To build a new agent from scratch: 1. Use `mcp` to scaffold a project for your target framework using your MCP description JSON. 2. Develop your agent logic and tools following Coral's conventions. 3. Link the agent locally with `coralizer link .`, then create a session on your Coral Server to run it. *** For more details on the `coralizer` CLI, see the [Coralizer GitHub repository](https://github.com/Coral-Protocol/coralizer). # Debugging Source: https://docs.coralos.ai/guides/debugging How to debug agents & sessions in Coral Server using built-in tools and the Puppet API. Coral provides several tools and techniques to help you debug your agents during development. These tools allow you to inspect the communication between agents, identify issues, and test individual components in isolation. ## Debugging with Coral Console The [Coral Console](/concepts/coral-console) is the easiest way to debug agents during development. It provides a real-time view of all agent interactions: * **Thread View:** See all messages sent and received in every thread, including agent-to-agent communication. * **Real-time Logs:** View the execution logs from every agent process. * **Agent Status:** Monitor the status of every agent (listening, busy, dead, etc.) in real-time. * **Agent Possession:** Take control of any agent and act on their behalf (via the [Puppet API](#puppet-api)) ## Puppet API The **Puppet API** allows an external application (like your own app or a debugging script) to "puppet" an agent. This means you can perform any action on behalf of a specific agent instance in a session. You can also use the Puppet API via [Coral Console](/concepts/coral-console). Expand **Agents** under a session, open the menu beside an agent, and choose **Possess**. The sidebar then shows **Acting as** that agent. Possess agent dropdown For more details on the Puppet API endpoints, see the [API Reference](/api-reference/puppet/create-thread). ## Built-in Debug Agents Coral Server includes built-in agents for testing and debugging. Enable them explicitly; they are disabled by default: ```toml theme={null} [registry] includeDebugAgents = true ``` Discover their installed versions through `GET /api/v1/registry`. Use `provider: { "type": "local", "runtime": "function" }` in session requests for these agents. They do not have Docker runtimes. All of these agents are hardcoded - they do **not** make any LLM completion requests ### `echo` * Automatically responds to any message it receives in its lifetime. ### `tool` * Calls a given tool when started. * Useful for testing custom tools or for kick starting activity in other agents. ### `seed` * Automatically sends messages across a given number of threads at a set interval. ### `puppet` * Does nothing on its own. * Serves as a "socket" for easily interacting with your session via the Puppet API. To include these agents in a session, reference them in your [`GraphAgentRequest`](/api-reference/models/GraphAgentRequest) like any other agent. ## Common Debugging Scenarios ### Verifying Agent Connections If an agent is not responding, check the agent's status in [Coral Console](/concepts/coral-console) to ensure that the agent has successfully been started & connected to the Coral Server's MCP. If the status is `Not connected` or `Stopped`, check the agent logs for errors. ### Isolating Agent Interactions To test an individual agent's logic, create a session that includes only that agent and one or more debug agents (like the [`puppet` agent](#puppet)). This allows you to test the agent's behavior in a controlled environment without the complexity of a full multi-agent graph. # Integrating with your application Source: https://docs.coralos.ai/guides/integrating-with-your-app Using Coral Server from, and integrating it with your application See also [this guide](/guides/production/running-in-production) on deploying Coral Server in production Use the [HTTP API](/api-reference/local/create-session) from your application to create sessions and handle results. Coral Console supports development and debugging. The public server also exposes Kotlin APIs for embedding; the HTTP integration described here works independently of your application's language. Coral Server also serves a dedicated API reference at `/ui/docs`. The OpenAPI schema is also available at `/api_v1.json`. ## Creating Sessions The create session endpoint is one of the most important endpoints - it's how you define and instantiate graphs of agents. While [Coral Console](/concepts/coral-console) has a ready-made interface over this endpoint, when integrating Coral with your application - you'll want to use this API directly. You can use the JSON available in [Coral Console's](/concepts/coral-console) editor pane when editing a session template - to quickly get a usable request body for your own POST to [`/api/v1/local/session`](/api-reference/local/create-session). Every application API call needs one of the server's [auth keys](/reference/server/auth) in an `Authorization: Bearer` header. Agent secrets do not authenticate these endpoints. ### Minimal request body The body is a [`SessionRequest`](/api-reference/models/SessionRequest). It needs an `agentGraphRequest` with at least one agent, and a `namespaceProvider`. ```json theme={null} { "agentGraphRequest": { "agents": [ { "id": { "name": "example-agent", "version": "0.1.0", "registrySourceId": { "type": "local" } }, "name": "example", "provider": { "type": "local", "runtime": "docker" }, "systemPrompt": "You are a helpful agent." } ] }, "namespaceProvider": { "type": "create_if_not_exists", "namespaceRequest": { "name": "demo", "deleteOnLastSessionExit": true } }, "execution": { "mode": "immediate", "runtimeSettings": { "ttl": 300000 } } } ``` ```bash theme={null} curl -X POST http://localhost:5555/api/v1/local/session \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $CORAL_TOKEN" \ -d @session.json ``` The response contains the session's `namespace` and `sessionId`. [Sessions](/concepts/sessions#session-lifecycle) describes what happens from creation to termination. ## Custom Tools There are a lot of scenarios where agents need to be given capabilities that are tightly integrated with your application. While you can hard code these kinds of tools in agents you write yourself, when using agents from other developers - this doesn't work. For this reason, Coral Server supports passing custom MCP tools to agents at runtime. When an agent calls one of these custom tools, Coral Server sends a request to an endpoint you provide, to know how to respond. ### Example - User Input A common use case in applications is exposing some kind of "chat"-style agent to your end users. This can be implemented using custom tools. One tool can request user input: Coral calls your application endpoint, and the endpoint's response supplies the user's answer to the waiting agent. A separate output tool can submit results or display progress. Long-lived user interactions need application storage and timeout handling. As an example, the flow for a user‑input custom tool looks (roughly) like: ```mermaid theme={null} sequenceDiagram participant App as Application App-->>Coral: Create session create participant Agent Coral-->>Agent: Instantiate Agent->>+Coral: Call to custom user‑input tool
(via MCP) Coral->>+App: POST to associated endpoint
(defined by app) Note over App: Present the request in
your application's frontend App->>-Coral: User response from frontend Coral->>-Agent: Response from app endpoint
(the user response) ``` ### Callback contract For an HTTP custom tool, Coral POSTs the tool argument object to your configured URL with `/{sessionId}/{agentName}` appended. It supplies `X-Coral-Namespace`, `X-Coral-SessionId`, and `X-Coral-AgentName` headers. Verify the `X-Coral-Signature` header against a lowercase hexadecimal HMAC-SHA256 over the exact request body bytes, using `network.customToolSecret`. The transport can override the signature header name. Return **HTTP 200** with the tool result. The public server wraps the response body in MCP text content. Other HTTP statuses become tool errors. Custom tool callbacks and end-report webhooks are separate contracts: end reports use `network.webhookSecret` and the exact configured URL. Signatures cover the body, not the URL or identity headers. Use a job-specific callback URL, check the expected session and agent against application-owned state, and make result handling idempotent. Store results before returning success. The public server does not provide a durable callback queue or a delivery guarantee. ### Complete application example `application.mjs` below is a runnable Node.js integration. It starts a callback server, verifies signatures before parsing JSON, creates a deferred session, saves the session-to-user mapping, and then starts execution. A distinct callback URL identifies each job. The example uses an in-memory map; replace it with shared durable storage for a deployed application. ```javascript application.mjs theme={null} import { createServer } from 'node:http'; import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto'; export function verifySignature(bytes, signature, secret) { if (typeof signature !== 'string' || !/^[a-f0-9]{64}$/i.test(signature)) return false; return timingSafeEqual(Buffer.from(signature, 'hex'), createHmac('sha256', secret).update(bytes).digest()); } // This runnable example uses memory for jobs. Use shared durable storage in a deployed application. export async function createReportApplication({ coralUrl, token, callbackSecret, callbackBaseUrl, port = 0 }) { if (!token || !callbackSecret) throw new Error('Server auth token and custom tool secret are required'); const jobs = new Map(); const server = createServer(async (req, res) => { const respond = (status, body) => { res.writeHead(status, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(body)); }; try { const parts = new URL(req.url, 'http://localhost').pathname.split('/').filter(Boolean); if (req.method !== 'POST' || parts.length !== 4 || parts[0] !== 'reports') return respond(404, { error: 'Unknown callback' }); const [, jobKey, sessionId, agentName] = parts.map(decodeURIComponent); const job = jobs.get(jobKey); if (!job || job.session?.sessionId !== sessionId || job.agentName !== agentName) return respond(404, { error: 'Unknown job' }); const chunks = []; let length = 0; for await (const chunk of req) { length += chunk.length; if (length > 1024 * 1024) return respond(413, { error: 'Report too large' }); chunks.push(chunk); } const raw = Buffer.concat(chunks); if (!verifySignature(raw, req.headers['x-coral-signature'], callbackSecret)) return respond(401, { error: 'Invalid signature' }); const report = JSON.parse(raw.toString('utf8')); if (typeof report.title !== 'string' || typeof report.content !== 'string') return respond(400, { error: 'Invalid report' }); if (!job.report) { // Persist the result under the trusted application's user/job mapping, never a user ID from the callback. job.report = { ...report, userId: job.userId }; job.resolve(job.report); } respond(200, { success: true, reportId: jobKey }); } catch { respond(400, { error: 'Invalid callback' }); } }); await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); }); const localUrl = `http://127.0.0.1:${server.address().port}`; const callbacks = (callbackBaseUrl ?? localUrl).replace(/\/$/, ''); async function api(path, body, method = 'POST') { const response = await fetch(coralUrl.replace(/\/$/, '') + path, { method, headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }, ...(body === undefined ? {} : { body: JSON.stringify(body) }), }); if (!response.ok) throw new Error(`Coral ${method} ${path}: ${response.status} ${await response.text()}`); const text = await response.text(); return text ? JSON.parse(text) : undefined; } return { localUrl, // Call only after authenticating the application user. `agent` is a full GraphAgentRequest. async startReport(userId, agent) { const jobKey = randomUUID(); let resolveResult; const result = new Promise(resolve => { resolveResult = resolve; }); const job = { userId, agentName: agent.name, resolve: resolveResult }; jobs.set(jobKey, job); let path; try { job.session = await api('/api/v1/local/session', { namespaceProvider: { type: 'create_if_not_exists', namespaceRequest: { name: 'reports', deleteOnLastSessionExit: true } }, execution: { mode: 'defer' }, agentGraphRequest: { agents: [{ ...agent, customToolAccess: [...new Set([...(agent.customToolAccess ?? []), 'submit_report'])] }], customTools: { submit_report: { description: 'Submit the finished report to the application', inputSchema: { type: 'object', properties: { title: { type: 'string' }, content: { type: 'string' } }, required: ['title', 'content'] }, outputSchema: { type: 'object', properties: { success: { type: 'boolean' }, reportId: { type: 'string' } } }, transport: { type: 'http', url: `${callbacks}/reports/${jobKey}` }, } }, }, }); // The mapping exists before execution starts, including callbacks made immediately at startup. path = `/api/v1/local/session/${encodeURIComponent(job.session.namespace)}/${encodeURIComponent(job.session.sessionId)}`; await api(path, { ttl: 300000, persistenceMode: { mode: 'hold_after_exit', duration: 60000 } }); return { session: job.session, result, async close() { try { await api(path, undefined, 'DELETE'); } finally { jobs.delete(jobKey); } }, }; } catch (error) { jobs.delete(jobKey); if (path) await api(path, undefined, 'DELETE').catch(() => {}); throw error; } }, async close() { server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); }, }; } ``` After copying that file, use it from your application's trusted backend: ```javascript theme={null} import { createReportApplication } from './application.mjs'; const app = await createReportApplication({ coralUrl: process.env.CORAL_SERVER_URL, token: process.env.CORAL_AUTH_TOKEN, callbackSecret: process.env.CORAL_CUSTOM_TOOL_SECRET, // For a remote server, use an HTTPS URL that forwards to this example's local listener. callbackBaseUrl: process.env.CALLBACK_BASE_URL, port: 8080 }); const job = await app.startReport('authenticated-user-id', { id: { name: 'report-writer', version: '1.0.0', registrySourceId: { type: 'local' } }, name: 'writer', provider: { type: 'local', runtime: 'prototype' }, options: { TASK: { type: 'string', value: 'Write a short report and call submit_report.' } } }); let timer; try { const timeout = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Report timed out')), 300000); }); const report = await Promise.race([job.result, timeout]); console.log(report); } finally { clearTimeout(timer); await job.close(); await app.close(); } ``` The sample uses a simple prototype to make the callback flow easy to reproduce. For production agents with custom context management or control flow, the [Koog template](/guides/quickstart#koog-template) is the main authoring path; the application API and callback contract stay the same. This example uses the complete [prototype agent definition](/reference/agent/tables/runtimes/prototype#complete-agent-definition). For Coral Cloud, discover an available agent and use the callback verification credentials supported by that deployment; do not assume your Cloud API key is a webhook signing secret. # Docker in Docker Source: https://docs.coralos.ai/guides/production/docker-in-docker Orchestrating Docker agents from inside Docker In order to allow Coral Server to spin up containers while being inside a Docker container itself, we need to mount the host's Docker socket into our container. Since Docker behaves differently on each platform - exactly how to do this varies: You can override the host Docker socket that Coral Server uses via: * Environment variable: `DOCKER_SOCKET` * JVM system properties: `CORAL_DOCKER_SOCKET`, `docker.socket`, or `docker.host` By default, on Windows, Coral will use `npipe:////./pipe/docker_engine`; on macOS with Colima it will use `unix://~/.colima/default/docker.sock`; otherwise `unix:///var/run/docker.sock`. # Linux Mounting `/var/run/docker.sock` should be enough to give the server the ability to spin up containers. ```bash theme={null} docker run -v /var/run/docker.sock:/var/run/docker.sock ... ``` # macOS We recommend you install [colima](https://github.com/abiosoft/colima) for a nicer experience. With colima, you can mount `~/.colima/default/docker.sock`: ```bash theme={null} docker run -v "$HOME/.colima/default/docker.sock:/var/run/docker.sock" ... ``` Without colima, you can mount `~/.docker/run/docker.sock` to the container: ```bash theme={null} docker run -v "$HOME/.docker/run/docker.sock:/var/run/docker.sock" ... ``` # Windows On Windows, Docker uses a named pipe by default. Prefer mapping the named pipe into the container: ```bash theme={null} docker run \ -v "//./pipe/docker_engine://./pipe/docker_engine" \ ... ``` If you are using WSL2 or a setup that exposes a Unix socket, you may also mount `//var/run/docker.sock`: ```bash theme={null} docker run -v "//var/run/docker.sock://var/run/docker.sock" ... ``` # Running in Production Source: https://docs.coralos.ai/guides/production/running-in-production Deploying Coral Server, and securing it in production # Deploying Coral Server The first step to running Coral Server in production is having a proper deployment of it. Exactly how you manage & deploy it depends on your application, but we offer a [docker image ](https://github.com/Coral-Protocol/coral-server/pkgs/container/coral-server) for Coral Server, and support orchestrating agents via Docker. ## Docker (recommended) Coral Server reads its main configuration from a TOML file specified by the `CONFIG_FILE_PATH` environment variable. When running from our provided Docker image, set `CONFIG_FILE_PATH` to `/config/config.toml` and mount a directory there. Agent discovery (the "registry") is configured inside `config.toml` via `registry.localAgents` glob patterns that point to directories containing `coral-agent.toml` files. There is no separate `REGISTRY_FILE_PATH` or `registry.toml` file. Create directories for the server configuration and your agent definitions: ```bash theme={null} mkdir -p my-config agents/my-agent # Place the agent's coral-agent.toml under agents/my-agent/. ``` Write `my-config/config.toml` before starting the server. Replace the example auth key and configure an LLM provider if your agents request one: ```toml theme={null} [auth] keys = ["replace-with-a-long-random-key"] [registry] localAgents = ["/agents/*"] includeCoralHomeAgents = false includeDebugAgents = false watchLocalAgents = true [console] enabled = false ``` For Docker agents, make the Docker daemon available as described in [Docker in Docker](/guides/production/docker-in-docker). On Linux with the standard socket: ```bash theme={null} docker run --rm \ -p 127.0.0.1:5555:5555 \ -v "$PWD/my-config:/config:ro" \ -v "$PWD/agents:/agents:ro" \ -v /var/run/docker.sock:/var/run/docker.sock \ -e CONFIG_FILE_PATH=/config/config.toml \ ghcr.io/coral-protocol/coral-server:latest ``` This binds the host-facing API to loopback. For a remote application or agents, expose the API through your deployment's network and authenticated HTTPS ingress, and configure an address that agent containers can actually reach. In particular, set `docker.address` when the default host gateway is not the machine running Coral. Agents using filesystem option transport require their temporary files to be visible at the same host paths to the Docker daemon. With a mounted host socket, container filesystem paths are not automatically host paths; use a shared directory mounted at the same absolute path and set the server JVM's `java.io.tmpdir` there. A remote daemon needs equivalent shared storage. Our provided docker image is *very* minimal! This means you should **not** (and usually can't) run agents through the `executable` runtime - and should use Docker orchestration for custom agent code. The built-in prototype runtime is also available without a child container. This is intended, as Docker orchestration is more stable, reproducible & portable - well suited for production. See [Docker in Docker](/guides/production/docker-in-docker) for steps to support Docker orchestration from inside Docker ## Java Clone the repo and build the jar file: ```bash theme={null} git clone https://github.com/Coral-Protocol/coral-server.git cd coral-server ./gradlew build --no-daemon -x test # the resulting .jar will end up in build/libs/coral-server-[..].jar ``` Use JDK 24. Create a configuration file containing at least `[auth]` and `keys`, as shown above, then run the actual built artifact from the repository root: ```bash theme={null} export CONFIG_FILE_PATH="$PWD/../coral-config/config.toml" # Create and populate that file before running this command. java -jar build/libs/coral-server-1.5.0.jar ``` For a different checkout, use the version in its `gradle.properties` and the corresponding file in `build/libs`. For reproducible deployments, select an actually published version-plus-commit image tag or pin an image digest. Do not assume a bare `1.5.0` or `v1.5.0` image tag exists; the workflow publishes branch, version-plus-commit, and build-number tags. The `latest` command above is a starting point, not a release pin. You should also consider writing a [systemd service ](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html) (or something similar) that runs your jar file for more reliable deployments. # Quickstart Source: https://docs.coralos.ai/guides/quickstart CoralOS Quickstart ## What is CoralOS? CoralOS is a platform for deploying and orchestrating agents that connect easily (with each other, your application, agentic middleware, ...) CoralOS consists of the Coral Server and supporting tooling/ecosystem. Think of CoralOS as the "Kubernetes for agents": you have a HTTP API, like a control plane, that lets you spin up a graph of agents with fully controlled lifecycles. ### What makes an agent a CoralOS agent? The basic requirements for an agent to run via Coral and be fully interoperable with the ecosystem are: * it can run in a container * it connects to the supplied unique MCP server URL passed to it With just those met, a whole host of things become possible: * Custom tools can be provided to any agent by the consuming application * Agents can discover and work with the other agents they are in groups with * Their lifecycles are fully managed, with configurable time-to-live for cost predictability. ### What are some more advanced features of CoralOS? CoralOS makes many more interesting things easy: * Pushing your agents to a [marketplace](https://marketplace.coralprotocol.ai/), where they may be used securely for free or become their own revenue streams * Agent re-usability via [exposable configuration (options)](/reference/agent/tables/options) * Safely intercept & manipulate LLM requests in-flight, to e.g. patch prompts, add memory to memoryless agents, or change the model used; without touching agent code (in-flight manipulation features coming soon) # Getting started Start by running Coral Server locally, then add your agents. Use Coral Console for development and debugging, and the API to create sessions from your application. Running the server is easy: Build and run the server with JDK 24 and Git installed. Docker is also required for agents using the Docker runtime. ```bash git + gradle theme={null} git clone --branch v1.5.0 https://github.com/Coral-Protocol/coral-server cd coral-server ``` Choose how your local server accesses language models. Both options work with your own Coral Server; Coral Console is available locally for development and debugging. Configure providers directly in `config.toml`. For example: ```toml config.toml theme={null} [[llm-proxy.providers]] name = "OpenAI" format.type = "OpenAI" api_key = "YOUR_OPENAI_API_KEY" base_url = "https://api.openai.com" models = ["gpt-4.1-mini", "gpt-5-mini"] [[llm-proxy.providers]] name = "Anthropic" format.type = "Anthropic" api_key = "YOUR_ANTHROPIC_API_KEY" base_url = "https://api.anthropic.com" models = ["claude-opus-4-6", "claude-sonnet-4-0"] ``` Keep the providers you use and include the models your agents request. See [LLM provider configuration](/reference/server/llm-proxy#providers) for more options. ```bash theme={null} CONFIG_FILE_PATH="$PWD/config.toml" ./gradlew run --args="--auth.keys=dev" ``` For convenience, a [Coral Cloud API key](/reference/server/cloud#api-key) automatically configures supported LLM providers and models. Your server and console still run locally; only model requests use the Cloud proxy. ```bash theme={null} ./gradlew run --args="--auth.keys=dev --cloud.api-key=coral..." ``` Built-in debug agents do not need an LLM provider. To start a server without model access: ```bash theme={null} ./gradlew run --args="--auth.keys=dev" ``` After the server starts, it prints an address to the Coral Console. You can "login" with the auth key `dev` or whatever you passed for the auth.keys parameter. Make sure to use a secure auth key in production, and follow conventional security practices when exposing your Coral Server to the public internet! Let's create a new agent from source to use in our server. We will use a template for convenience, but writing agents in any framework (or modifying existing to work with Coral) is also easy. See [this guide](/guides/writing-agents) on writing agents for more information on agent requirements. ```bash npm theme={null} npm create koog -- my-first-agent --agentName=my-first-agent --packageName=com.example.myfirstagent --keepWorkflows=true --keepPublishJvm=true --keepPublishNative=true --keepReleasePlease=true ``` ```bash git + gradle theme={null} git clone https://github.com/Coral-Protocol/coral-koog-agent my-first-agent cd my-first-agent ./gradlew hydrate my-first-agent ``` Check the template's own README for its JDK requirement; it can differ from Coral Server's JDK 24 requirement. This will create a Kotlin agent using JetBrain's wonderful [Koog framework ](https://docs.koog.ai/) You should now have a file structure that looks something like this: `coral-agent.toml` is Coral's entrypoint to this agent, with all relevant agent metadata (runtime, options, etc). Learn more about it [here](/reference/agent) | Language | Framework | Maturity | Repositories | | - | - | - | - | | Rust | coral-rs (Rig) | Low | [Deepwiki Agent ](https://github.com/Coral-Protocol/agents/blob/main/rust/agent-deepwiki/src/main.rs) | | Kotlin | Koog | High | [Template ](https://github.com/Coral-Protocol/coral-koog-agent) | | Python | LangChain | Low | [Template ](https://github.com/Coral-Protocol/langchain-agent) | Missing any? Come to [our discord ](https://discord.gg/2subZkSWWu) to share your own examples or ask for relevant ones. Open a terminal in your generated `my-first-agent` directory, then link it so servers on that machine can discover it: ```bash theme={null} npx @coral-protocol/coralizer@latest link . ``` On Windows, you may need to run as administrator to avoid permission issues creating the symlink This creates a symlink called `~/.coral/agents/my-first-agent/{agentVersion}` pointing to your agent's directory To "unlink" this agent, you can run: ```bash theme={null} unlink ~/.coral/agents/my-first-agent/{version} # replace {version} with your agent's version (as seen in the coral-agent.toml) ``` Now that you have agent(s) in your server, you can create a multi agent session! Creating a session can be done in [one POST request](/api-reference/local/create-session), but for a more convenient experience, you can use Coral Console. Open your browser and go to [http://localhost:5555/ui/console](http://localhost:5555/ui/console). The screenshots show Console v0.3.18; to select this version, start the server with `--console.console-release-version=v0.3.18`. Open **Workbench** and choose **New file**. Give the session request a name. Coral Console Workbench with a session request and its agents In the **Agents** panel, find your agent and click **Add**. Select it in the diagram or **Outline**, then use **Inspector** to configure its options. Configure the required agent options in **Inspector**. In **Groups**, put agents that need to communicate in the same group. Use the **Session** panel to set the budget and TTL (time-to-live), which determines how long the session can run before it is automatically terminated. Optionally, click **Save request** to save the configuration for reuse. Click **Create session** to start your agents. 1. Expand the session you just started under **Sessions** in the sidebar. 2. Expand **Agents**, select an agent, and inspect its status and **Logs**. 3. Expand **Threads** to inspect the conversation. Ultimately it's intended that Coral sessions are instantiated via code. Coral Console provides the needed JSON payload for the [create session endpoint](/api-reference/local/create-session), as well as code snippets that include making the request. Coral Server requires a bearer token for application REST endpoints. We set our auth key to `dev` in [Step 1](#run-the-server), so use the header `Authorization: Bearer dev`. The documentation endpoints are public, while agents use their own MCP URLs and agent RPC credentials. The server's `auth.keys` authenticate these API requests. LLM provider keys, including the Coral Cloud proxy key, are configured separately on the server. Make sure to use a secure auth key, and follow conventional security practices when exposing your Coral Server to the public internet! Naturally, variable substitution and environment variables should be used over hardcoding every option value, since sensitive information like API keys can be passed as agent options. That wraps up the CoralOS quickstart! Next, see [Integrating with your app](/guides/integrating-with-your-app). # Writing Agents Source: https://docs.coralos.ai/guides/writing-agents How to write agents that work with Coral Server # Prerequisites * A running instance of [Coral Server](https://github.com/Coral-Protocol/coral-server?tab=readme-ov-file#how-to-run) * An existing agent you want to onboard to Coral # Modifying your agent Start with the [Koog template](/guides/quickstart#koog-template) when writing a new agent. It is also the reference when porting to another framework. Agent code is the place to control context management, memory, and execution flow. The [prototype runtime](/reference/agent/tables/runtimes/prototype) is a smaller option for cases known to need only a simple LLM/tool loop. To build an agent around existing MCP servers, or to port an existing agent, we recommend asking a coding agent such as Codex or Claude Code to do it, using the [Koog agent template](https://github.com/Coral-Protocol/coral-koog-agent) as a reference. Give it this page as the contract the result must meet. [Coralizer](/guides/coralizer#converting-an-mcp-server) has an example prompt. Agents interact with Coral sessions exclusively through a uniquely provided MCP server. All interaction with other agents is then done with the tools available through that MCP. ### Connect to Coral Since each agent in a session is given its own MCP - your agent must receive the MCP's connection url dynamically. When running the agent through Coral Server's orchestrator, that is provided by the `CORAL_CONNECTION_URL` environment variable. Here are some example snippets for popular Python frameworks: These snippets are **not** complete implementations, or guaranteed to work as is for your agent! Actual integration heavily depends on your agent's existing implementation. ```python CAMEL-AI theme={null} import os from camel.toolkits.mcp_toolkit import MCPClient from camel.utils.mcp_client import ServerConfig coral_url = os.environ["CORAL_CONNECTION_URL"] # Provided by Coral Server at runtime prefer_sse = coral_url.endswith("/sse/") # Use SSE only when the URL is an SSE endpoint coral_mcp = MCPClient( ServerConfig( url=coral_url, timeout=3000000.0, # Long timeouts since wait_for_mentions, etc. can take a long time. sse_read_timeout=3000000.0, terminate_on_close=True, prefer_sse=prefer_sse ), timeout=3000000.0 ) ``` The server provides a per-agent MCP connection URL via `CORAL_CONNECTION_URL`. It may point to the Streamable HTTP endpoint (`/mcp/v1/{agentSecret}/mcp`) or the SSE endpoint (`/mcp/v1/{agentSecret}/sse/`). For SSE, a trailing slash is required. Do not hardcode this URL — always use the exact value provided. ### Agent Configuration Agents have a lot of options that users would want to change. API keys, models, providers, and even sampling parameters (temperature, top\_p) - are all things we want to accept dynamically. Coral's orchestrator provides an 'option' system, that allows you - the agent developer - to expose specific typed options, and receive the values of those options as environment variables. This means you should **not** load `.env` files by default, since environment variables should *only* be provided by Coral Server. See [Agent Options](#agent-options) for details on how to expose your configuration options. # Packaging your agent Now that your agent works with Coral, to make it work with orchestration - you need to package your agent. In the root of your agent repository/folder, create a `coral-agent.toml` file. Add its directory to `registry.localAgents` in the server's `config.toml`, or use `coralizer link .`. There is no separate `registry.toml`. An agent definition starts with basic metadata: ```toml theme={null} edition = 5 [agent] name = "name-of-my-agent" version = "0.1.0" # agent version (should be semver) description = "Description of this agent's capabilities, that is shown to other agents" summary = "A short description for users" readme = "Documentation for users of this agent." license = { type = "spdx", expression = "MIT" } ``` ### Agent Options Coral's orchestrator allows you to expose specific typed options, to be passed to your agent on instantiation as environment variables. `options` are a map of option names, to user configurable options you want to expose. Each option has: The type of the option (e.g., `string`, `i32`, `f64`, `bool`, `list[string]`, etc.). A description of what this option configures in your agent. The default value of this option if not provided. The type must match the specified `type`. Whether this option is required. `false` by default. If `true`, the value is masked in configuration displays and server-generated option log entries. Agent stdout/stderr is not automatically redacted; the agent must avoid logging secrets. ```toml theme={null} edition = 5 [agent] name = "my-discord-agent" version = "1.1.0" description = "Handles application tasks in Discord" summary = "Discord integration agent" readme = "Configure the Discord token and thread before running this agent." license = { type = "spdx", expression = "MIT" } [options.DISCORD_API_TOKEN] type = "string" required = true secret = true display.description = "Discord API token" [options.DISCORD_THREAD_ID] type = "string" required = true display.description = "The ID of the thread to watch" [options.OPENROUTER_API_KEY] type = "string" required = true secret = true display.description = "An API key for OpenRouter" ``` ### Agent Runtimes Coral Server supports `docker`, `executable` (local subprocess), and [prototype](/reference/agent/tables/runtimes/prototype) (a built-in LLM/tool loop). The `function` runtime is an in-process Kotlin API used by built-in debug agents and embedded applications; it cannot be defined as executable code in `coral-agent.toml`. It's recommended you support Docker if you intend to publish your agent, or export it as a remote agent (closed beta). Running your agent via docker naturally requires your agent to be containerized. How you containerize your agent depends a lot on how your agent is written - what language it uses, how it manages dependencies, etc. Feel free to browse our curated list of agents [here](https://github.com/Coral-Protocol/awesome-agents-for-multi-agent-systems) for reference on packaging Python agents for Docker using [uv](https://docs.astral.sh/uv/). Once it is, you simply reference your image in the `coral-agent.toml`: ```toml theme={null} [runtimes.docker] image = "name-of-docker-image" # whatever you would put in `docker run [image]` ``` While specifiying a tag does work, we recommend you do **not** add one, since Coral Server will use the agent's defined version (as seen earlier) as the docker tag (for better reproducibility). This means you **must** tag your images with the agent's version when publishing to a container registry. For agents only intended to be ran by your own local coral servers, just having the image built & present locally is enough. For public agents, you need to make sure the image is available on a registry like [Docker Hub](https://hub.docker.com/) or [Github's Container registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) This runtime is even more implementation dependent - since you are running a command/process directly on the same host as the server. It's also not portable, since it's hard to account for all possible system environments. For these reasons it's recommended you use the Docker runtime whenever possible. A good pattern to maximise portability is writing wrapper scripts for each OS you want to support, that handles ensuring dependencies are present/downloaded (e.g. create/enter a python virtual environment, download dependencies) Here's an example of a bootstrap script we use for [our agents](https://github.com/Coral-Protocol/awesome-agents-for-multi-agent-systems): ```sh run_agent.sh theme={null} #!/usr/bin/env bash set -e PYTHON_SCRIPT="main.py" # Determine script directory SCRIPT_DIR=$(dirname "$(realpath "$0" 2>/dev/null || readlink -f "$0" 2>/dev/null || echo "$0")") PROJECT_DIR="$SCRIPT_DIR" echo "Agent directory: $PROJECT_DIR" # Change to project directory cd "$PROJECT_DIR" echo "Running $PYTHON_SCRIPT..." uv run "$PYTHON_SCRIPT" ``` Adding this runtime to your `coral-agent.toml` would look something like: ```toml theme={null} [runtimes.executable] path = "bash" arguments = ["run_agent.sh"] # each 'word' of your command should be a separate item in the array, to minimise issues with argument parsing ``` ### Runtime transport (agent↔server) Agents communicate with Coral Server using MCP over HTTP. Two transport modes are supported by all runtimes: * `streamable_http` (default) * `sse` (legacy Server‑Sent Events) Select the mode per runtime with the optional `transport` field in `coral-agent.toml`: ```toml theme={null} [runtimes.docker] image = "name-of-docker-image" transport = "streamable_http" # default [runtimes.executable] path = "./launch" arguments = ["my-agent"] transport = "sse" # opt into SSE if your agent expects it ``` # Orchestration Environment Agents run under orchestration are provided with a set of "system" environment variables that are needed/useful to work with Coral: | Variable | Description | | :- | :- | | `CORAL_CONNECTION_URL` | The MCP connection URL for this agent. Defaults to Streamable HTTP; may be SSE depending on the selected runtime transport. | | `CORAL_AGENT_ID` | The unique name of the agent instance in the session. | | `CORAL_AGENT_SECRET` | A unique secret used to authenticate with the server's MCP endpoints. | | `CORAL_SESSION_ID` | The ID of the session the agent belongs to. | | `CORAL_API_URL` | The URL of the Coral Server's REST API. | | `CORAL_RUNTIME_ID` | The orchestration runtime being used. | | `CORAL_PROMPT_SYSTEM` | Additional system instructions provided at session creation. | | `CORAL_PROXY_URL_` | Base URL for a resolved LLM proxy request. | | `CORAL_PROXY_FORMAT_` | Provider format for that proxy request. | | `CORAL_PROXY_MODEL_` | Selected model for that proxy request. | `CORAL_SEND_CLAIMS`, `CORAL_REMOTE_AGENT`, `CORAL_STATE_RESOURCE_URI`, and `CORAL_INSTRUCTION_RESOURCE_URI` are not emitted for local Docker/executable agents in public Server 1.5.0. Prototype runtimes consume configuration in-process instead of launching an environment-configured child process. # Local iteration tips During development, we recommend: * Use the `executable` runtime to iterate locally, or containerize early and use the `docker` runtime for parity. * Make your agent discoverable to Coral Server with `coralizer link .` so it appears in the local registry. * Create a session via the REST API at `POST http://localhost:5555/api/v1/local/session` to launch and test your agent. Do not hardcode MCP connection URLs or load `.env` overrides while running under orchestration. Always rely on the `CORAL_*` variables supplied by Coral Server. # Vibecoding Source: https://docs.coralos.ai/help/vibecoding Guidelines and warnings on LLM-assisted coding with CoralOS Making agents or adding existing agents to Coral is easy, but there are some important considerations when using LLMs for coding tasks. ## Tl;dr Recent models work well with Coral and MCP. In Claude Code or Codex, install the Coral skill, which gives the agent these docs and Coral's usage model: ```text Claude Code theme={null} /plugin marketplace add Coral-Protocol/coral-skill-set /plugin install coral-skills@coral-skill-set ``` ```bash Codex theme={null} codex plugin marketplace add Coral-Protocol/coral-skill-set codex plugin add coral-skills@coral-skill-set ``` ## DeepWiki [DeepWiki](https://deepwiki.com/Coral-Protocol/coral-server) provides an LLM-generated documentation of the coral server's code. It is generally pretty accurate. It can be asked questions directly, or be used as a source of truth for other agents. ## Prompt engineering When using LLMs for coding tasks, prompt engineering is crucial. Here are some tips: * Encourage the model to ask questions to you about Coral and MCP if it is unsure. * Work from high quality up to date examples. * For agentic coding tools without access to DeepWiki, consider giving them access to the coral server source ## Warnings Vibe coding can engage less familiar developers and allow people to get started faster, but it is not a substitute for understanding the underlying technology and your solution. Typing is rarely the bottleneck in software development. It is easy to fall into a trap where you have a solution that seems to work, but you don't understand how it works or how to fix it when it breaks. # Agent configuration Source: https://docs.coralos.ai/reference/agent The `coral-agent.toml` file Agents are created and configured using a `coral-agent.toml` file. Every agent in Coral (Server, Console, Cloud and Marketplace) has exactly one `coral-agent.toml` file. # Syntax A `coral-agent.toml` file is written in [TOML](https://toml.io/). This file has a single top-level field, `edition` and configuration tables. ## Edition The top-level `edition` field is a number indicating the edition of the `coral-agent.toml` file, allowing the Coral server and other applications to quickly identify whether or not they are compatible. **The current edition is 5.** Public Coral Server 1.5.0 accepts editions 3 through 5. Older editions still need the required metadata and valid runtime/options fields. ## Tables ### [agent table](/reference/agent/tables/agent) Contains basic information about the agent, such as its name and version. This table is required, and many of its fields are required. ### Runtimes table An agent **must define 1 or more** of the following: | Runtime | Environment | Description | | - | - | - | | [runtimes.executable](/reference/agent/tables/runtimes/executable) | development | Used exclusively for development. Cannot be used in the marketplace. | | [runtimes.docker](/reference/agent/tables/runtimes/docker) | production | Production runtime custom agents, highly configurable | | [runtimes.prototype](/reference/agent/tables/runtimes/prototype) | production, development | Limited configuration, but can be used for rapid agent prototyping and production | ### [options table](/reference/agent/tables/options) The `options` table contains up to 512 unique options that allow your agent to be configured at runtime, by applications. Options are optional; however, almost every agent will have options. Options are for example used for: * API keys used by LLMs * API keys or tokens used by MCP servers * Prompting adjustments ### [llm table](/reference/agent/tables/llm) A table that describes the LLM requirements of the agent. This table is optional; however, agents that do not use LLM proxies will be limited in what Coral features they support. # [agent] Source: https://docs.coralos.ai/reference/agent/tables/agent General agent information ## agent.name required A [string](https://toml.io/en/v1.1.0#string) defining the name for the agent. ```toml theme={null} [agent] name = "my-agent" ``` **Requirements** * At least one character * No more than 32 characters * Must match `^[a-z0-9]([a-z0-9]*(-[a-z0-9]+)*)?$`: lowercase letters/digits separated by single dashes, without a leading or trailing dash ## agent.version required A [string](https://toml.io/en/v1.1.0#string) defining the version of the agent. ```toml theme={null} [agent] version = "1.0.0" ``` **Requirements** * At least one character * No more than 24 characters * Must be a valid [semantic version](https://semver.org/) ## agent.description required A [PotentialStringReference](/reference/types/potential-string-reference) description for this agent. This description is exclusively used by LLMs. This description is only a default and may be overridden at runtime. Agent descriptions are provided to agents in the state resource. ```toml theme={null} [agent] description = "An agent with web search capabilities" ``` **Requirements** * At least one character * No more than 1024 characters ## agent.capabilities optional An [array](https://toml.io/en/v1.1.0#array) of capabilities. ```toml theme={null} [agent] capabilities = ["resources", "tool_refreshing"] ``` This is a placeholder field. Currently, this has no use. **Requirements** * All entries must be one of the following: * `resources` * `tool_refreshing` * Must not contain duplicates ## agent.readme required A [PotentialStringReference](/reference/types/potential-string-reference) readme for this agent. This readme is displayed in the Coral marketplace and in Coral console. The summary is not provided in the state resource. In Coral console and in Coral marketplace the readme supports markdown. ```toml theme={null} [agent] readme = """ A long descriptive readme for my agent. """ ``` **Requirements** * At least one character * No more than 4096 characters ## agent.summary required A [PotentialStringReference](/reference/types/potential-string-reference) summary for this agent. This summary is displayed in the Coral marketplace and in Coral console. The summary is not provided in the state resource. ```toml theme={null} [agent] summary = "An agent with web search capabilities" ``` **Requirements** * At least one character * No more than 256 characters ## agent.license required The license for this agent. Licenses may be specified as an [SPDX expression](https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/) or text via the [PotentialStringReference](/reference/types/potential-string-reference) type. The license will be displayed in the Coral marketplace. ```toml theme={null} [agent.license] type = "spdx" expression = "MIT" ``` **Requirements** * The expression must be valid. See [here](https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions) for more information. ```toml theme={null} [agent.license] type = "text" text = { type = "file", path = "LICENSE.TXT" } ``` **Requirements** * The license text must not be larger than 2 MiB ## agent.keywords optional An [array](https://toml.io/en/v1.1.0#array) of [string](https://toml.io/en/v1.1.0#string) keywords to describe this agent. These keywords are used by the Coral marketplace and the Coral console agent registry to search for agents. ```toml theme={null} [agent] keywords = ["web", "search"] ``` **Requirements** * Each keyword must contain at least one character * Each keyword must not contain more than 64 characters * Must not contain duplicates * Must not contain more than 256 keywords ## agent.links optional A [table](https://toml.io/en/v1.1.0#table) of [strings](https://toml.io/en/v1.1.0#string), where the key is the link name and the value is the link URL. These links are displayed in the Coral marketplace and in the Coral console. ```toml theme={null} [agent] links.github = "https://github.com/coral-Protocol/coral-server" links.home = "https://www.coralos.ai" ``` **Requirements** * Link names must start with an alphabetic character * Link names must contain only alphanumeric characters, underscores (`_`) and dashes (`-`) * Link names must be at least one character long and at most 32 characters long * Link values must be at least one character long and at most 256 characters long * Link values must be a valid URL * Link values must be either `https`, `mailto` or `tel` * No more than 16 links may be specified # [llm] Source: https://docs.coralos.ai/reference/agent/tables/llm Agent LLM requirements ### llm.proxies optional An array of [AgentLlmProxyRequest](/reference/types/agent-llm-proxy-request) describing requests for LLM proxies to be used by this agent. The [AgentLlmProxyRequest](/reference/types/agent-llm-proxy-request) page serves as the documentation for this array. All proxies listed must be satisfied for the server to launch the agent. Application developers that attempt to create sessions with agents that request unavailable proxies will receive an error. ```toml theme={null} [[llm.proxies]] name = "OPENAI" format.type = "OpenAI" models = ["gpt-5"] [[llm.proxies]] name = "ANTHROPIC" format.type = "Anthropic" models = ["claude-3-opus"] ``` **Requirements** * There may be at most 16 proxy requests defined. # options table Source: https://docs.coralos.ai/reference/agent/tables/options Configuration options for an agent. Options allow an agent to be configured or tweaked at runtime. All options, unless specified as optional, will be provided to the agent by the server as environment variables. An agent that has required options with no default values will require the user to specify values for those options. ```toml theme={null} [options.EXAMPLE_OPTION] type = "string" [options.EXAMPLE_REQUIRED_OPTION] type = "string" required = true [options.EXAMPLE_DEFAULT_OPTION] type = "string" default = "default value for this option" ``` ## Requirements * Option names must be between 1 and 256 characters * Option names must match `^[a-zA-Z_][a-zA-Z_$0-9]*$`: start with a letter or underscore, followed by letters, digits, underscores or `$` * An agent may only specify 512 options * The combined size of all default values for all options may not exceed 6 MiB ## Types All options must specify a type. Different option types have different fields. Available option types: | Type | List type | Description | | - | - | - | | [i8](/reference/agent/tables/options/i8) | [list\[i8\]](/reference/agent/tables/options/i8#list) | 8-bit signed integer | | [i16](/reference/agent/tables/options/i16) | [list\[i16\]](/reference/agent/tables/options/i16#list) | 16-bit signed integer | | [i32](/reference/agent/tables/options/i32) | [list\[i32\]](/reference/agent/tables/options/i32#list) | 32-bit signed integer | | [i64](/reference/agent/tables/options/i64) | [list\[i64\]](/reference/agent/tables/options/i64#list) | 64-bit signed integer | | [u8](/reference/agent/tables/options/u8) | [list\[u8\]](/reference/agent/tables/options/u8#list) | 8-bit unsigned integer | | [u16](/reference/agent/tables/options/u16) | [list\[u16\]](/reference/agent/tables/options/u16#list) | 16-bit unsigned integer | | [u32](/reference/agent/tables/options/u32) | [list\[u32\]](/reference/agent/tables/options/u32#list) | 32-bit unsigned integer | | [u64](/reference/agent/tables/options/u64) | [list\[u64\]](/reference/agent/tables/options/u64#list) | 64-bit unsigned integer | | [f32](/reference/agent/tables/options/f32) | [list\[f32\]](/reference/agent/tables/options/f32#list) | 32-bit floating-point number | | [f64](/reference/agent/tables/options/f64) | [list\[f64\]](/reference/agent/tables/options/f64#list) | 64-bit floating-point number | | [bool](/reference/agent/tables/options/bool) | — | Boolean value | | [string](/reference/agent/tables/options/string) | [list\[string\]](/reference/agent/tables/options/string#list) | UTF-8 string | | [blob](/reference/agent/tables/options/blob) | [list\[blob\]](/reference/agent/tables/options/blob#list) | Binary data | # blob option type Source: https://docs.coralos.ai/reference/agent/tables/options/blob A blob option. Blobs should be used for options that might contain binary data. Blobs should use the [filesystem transport](/reference/agent/tables/options/blob#filesystem-transport). | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | `my option value` | `6D 79 20 6F 70 74 69 6F 6E 20 76 61 6C 75 65` | `bXkgb3B0aW9uIHZhbHVl` | | | (binary) | (base64, by default) | ## Full example ```toml theme={null} [options.EXAMPLE_BLOB_OPTION] type = "blob" transport = "fs" required = false default = { type = "file", path = "image.png" } display.label = "Example Blob Option" display.description = "This is an example blob option." display.group = "Example Group" validation.min_size = { size = 1.0, unit = "KiB" } validation.max_size = { size = 1.0, unit = "MiB" } ``` ```toml theme={null} [options.EXAMPLE_BLOB_OPTION] type = "list[blob]" transport = "fs" required = false default = [ { type = "file", path = "icon1.png" }, { type = "file", path = "icon2.png" } ] display.label = "Example Blob List Option" display.description = "This is an example blob list option." display.group = "Example Group" validation.min_size = { size = 1.0, unit = "KiB" } validation.max_size = { size = 2.0, unit = "KiB" } ``` ## option.type required ```toml theme={null} type = "blob" ``` ```toml theme={null} type = "list[blob]" ``` ## option.default optional A [PotentialStringReference](/reference/types/potential-string-reference) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. File or URL references will by default have `base64 = true` ```toml theme={null} default = { type = "file", path = "image.png" } ``` An [array](https://toml.io/en/v1.1.0#array) of [PotentialStringReferences](/reference/types/potential-string-reference) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. File or URL references will by default have `base64 = true` ```toml theme={null} default = [ { type = "file", path = "image1.png" }, { type = "file", path = "image2.png" } ] ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.validation The server performs option validation before running an agent. The Coral server will never launch an agent with option values that do not pass the validation rules given for an option. The absence of a validation rule indicates that the absent validation rule should not be performed. No validation rules have default values. For list types, validation will be performed on each item on the list. A single invalid item will reject the entire list. ### option.validation.min\_size optional A [ByteSize](/reference/types/byte-size) value specifying the minimum number of bytes in the blob. ```toml theme={null} validation.min_size = "1.0 KiB" ``` ### option.validation.max\_size optional A [ByteSize](/reference/types/byte-size) value specifying the maximum number of bytes in the blob. ```toml theme={null} validation.max_size = "1.0 MiB" ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` # bool option type Source: https://docs.coralos.ai/reference/agent/tables/options/bool A boolean option. Booleans should use the [environment transport](/reference/agent/tables/options/bool#environment-transport) as they are never large enough to use the [filesystem transport](/reference/agent/tables/options/bool#filesystem-transport). Booleans do not have a list type | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | `true` | `0x01` | `1` | | `false` | `0x00` | `0` | | | (binary) | (utf-8 string) | ## Full example ```toml theme={null} [options.EXAMPLE_BOOL_OPTION] type = "bool" required = false default = true display.label = "Example Boolean Option" display.description = "This is an example boolean option." display.group = "Example Group" ``` ## option.type required ```toml theme={null} type = "bool" ``` ## option.default optional A [boolean](https://toml.io/en/v1.1.0#boolean) specifying the default value for this option. ```toml theme={null} default = true ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` # f32 option type Source: https://docs.coralos.ai/reference/agent/tables/options/f32 A . Floats should use the [environment transport](#environment-transport) as they are never large enough to use the [filesystem transport](#filesystem-transport). | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | | (IEEE 754 -precision, big-endian) | (utf8) | ## Full example ```toml theme={null} [options.EXAMPLE_F32_OPTION] type = "f32" required = false default = 3.14159265359 display.label = "Example f32 Option" display.description = "This is an example f32 option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0] validation.min = -10.0 validation.max = 10.0 ``` ```toml theme={null} [options.EXAMPLE_F32_OPTION] type = "list[f32]" required = false default = [3.14159265359, 2.71828182846] display.label = "Example f32 Option" display.description = "This is an example f32 option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0] validation.min = -10.0 validation.max = 10.0 ``` ## option.type required ```toml theme={null} type = "f32" ``` ```toml theme={null} type = "list[f32]" ``` ## option.default optional An [float](https://toml.io/en/v1.1.0#float) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = 3.14159265359 ``` An [array](https://toml.io/en/v1.1.0#array) of [floats](https://toml.io/en/v1.1.0#float) specifying the default values for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = [3.14159265359, 2.71828182846] ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.validation The server performs option validation before running an agent. The Coral server will never launch an agent with option values that do not pass the validation rules given for an option. The absence of a validation rule indicates that the absent validation rule should not be performed. No validation rules have default values. For list types, validation will be performed on each item on the list. A single invalid item will reject the entire list. ### option.validation.variants optional An [array](https://toml.io/en/v1.1.0#array) of [floats](https://toml.io/en/v1.1.0#string) that specify valid values for this option. If `variants` is specified, the value for this option must be one of the entries in `variants`. This is usually used to construct an enum. ```toml theme={null} validation.variants = [3.14159265359, 2.71828182846, 1.41421356237] ``` ### option.validation.min optional A [float](https://toml.io/en/v1.1.0#float) specifying the minimum allowed value for this option. ```toml theme={null} validation.min = -100.0 ``` ### option.validation.max optional A [float](https://toml.io/en/v1.1.0#float) specifying the maximum allowed value for this option. ```toml theme={null} validation.max = 100.0 ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` # f64 option type Source: https://docs.coralos.ai/reference/agent/tables/options/f64 A . Floats should use the [environment transport](#environment-transport) as they are never large enough to use the [filesystem transport](#filesystem-transport). | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | | (IEEE 754 -precision, big-endian) | (utf8) | ## Full example ```toml theme={null} [options.EXAMPLE_F64_OPTION] type = "f64" required = false default = 3.141592653589793 display.label = "Example f64 Option" display.description = "This is an example f64 option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0] validation.min = -10.0 validation.max = 10.0 ``` ```toml theme={null} [options.EXAMPLE_F64_OPTION] type = "list[f64]" required = false default = [3.141592653589793, 2.718281828459045] display.label = "Example f64 List Option" display.description = "This is an example f64 list option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0] validation.min = -10.0 validation.max = 10.0 ``` ## option.type required ```toml theme={null} type = "f64" ``` ```toml theme={null} type = "list[f64]" ``` ## option.default optional An [float](https://toml.io/en/v1.1.0#float) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = 3.14159265359 ``` An [array](https://toml.io/en/v1.1.0#array) of [floats](https://toml.io/en/v1.1.0#float) specifying the default values for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = [3.14159265359, 2.71828182846] ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.validation The server performs option validation before running an agent. The Coral server will never launch an agent with option values that do not pass the validation rules given for an option. The absence of a validation rule indicates that the absent validation rule should not be performed. No validation rules have default values. For list types, validation will be performed on each item on the list. A single invalid item will reject the entire list. ### option.validation.variants optional An [array](https://toml.io/en/v1.1.0#array) of [floats](https://toml.io/en/v1.1.0#string) that specify valid values for this option. If `variants` is specified, the value for this option must be one of the entries in `variants`. This is usually used to construct an enum. ```toml theme={null} validation.variants = [3.14159265359, 2.71828182846, 1.41421356237] ``` ### option.validation.min optional A [float](https://toml.io/en/v1.1.0#float) specifying the minimum allowed value for this option. ```toml theme={null} validation.min = -100.0 ``` ### option.validation.max optional A [float](https://toml.io/en/v1.1.0#float) specifying the maximum allowed value for this option. ```toml theme={null} validation.max = 100.0 ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` # i16 option type Source: https://docs.coralos.ai/reference/agent/tables/options/i16 A . Integers should use the [environment transport](#environment-transport) as they are never large enough to use the [filesystem transport](#filesystem-transport). s have a minimum value of and a maximum value of . This range must be respected in values given for this option and values specified as defaults or for validation. | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | | (binary, big-endian) | (utf8) | ## Full example ```toml theme={null} [options.EXAMPLE_I16_OPTION] type = "i16" required = false default = 500 display.label = "Example i16 Option" display.description = "This is an example i16 option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 250, 500, 750, 1000] validation.min = 0 validation.max = 1000 ``` ```toml theme={null} [options.EXAMPLE_I16_OPTION] type = "list[i16]" required = false default = [0, 500, 1000] display.label = "Example i16 List Option" display.description = "This is an example i16 list option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 250, 500, 750, 1000] validation.min = 0 validation.max = 1000 ``` ## option.type required ```toml theme={null} type = "i16" ``` ```toml theme={null} type = "list[i16]" ``` ## option.default optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = 1000 ``` An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) specifying the default values for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = [1000, 2000, 3000] ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.validation The server performs option validation before running an agent. The Coral server will never launch an agent with option values that do not pass the validation rules given for an option. The absence of a validation rule indicates that the absent validation rule should not be performed. No validation rules have default values. For list types, validation will be performed on each item on the list. A single invalid item will reject the entire list. ### option.validation.variants optional An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) that specify valid values for this option. If `variants` is specified, the value for this option must be one of the entries in `variants`. This is usually used to construct an enum. ```toml theme={null} validation.variants = [1, 2, 3] ``` ### option.validation.min optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the minimum allowed value for this option. ```toml theme={null} validation.min = 0 ``` ### option.validation.max optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the maximum allowed value for this option. ```toml theme={null} validation.max = 100 ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` # i32 option type Source: https://docs.coralos.ai/reference/agent/tables/options/i32 A . Integers should use the [environment transport](#environment-transport) as they are never large enough to use the [filesystem transport](#filesystem-transport). s have a minimum value of and a maximum value of . This range must be respected in values given for this option and values specified as defaults or for validation. | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | | (binary, big-endian) | (utf8) | ## Full example ```toml theme={null} [options.EXAMPLE_I32_OPTION] type = "i32" required = false default = 5000 display.label = "Example i32 Option" display.description = "This is an example i32 option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 2500, 5000, 7500, 10000] validation.min = 0 validation.max = 10000 ``` ```toml theme={null} [options.EXAMPLE_I32_OPTION] type = "list[i32]" required = false default = [0, 5000, 10000] display.label = "Example i32 List Option" display.description = "This is an example i32 list option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 2500, 5000, 7500, 10000] validation.min = 0 validation.max = 10000 ``` ## option.type required ```toml theme={null} type = "i32" ``` ```toml theme={null} type = "list[i32]" ``` ## option.default optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = 1000 ``` An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) specifying the default values for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = [1000, 2000, 3000] ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.validation The server performs option validation before running an agent. The Coral server will never launch an agent with option values that do not pass the validation rules given for an option. The absence of a validation rule indicates that the absent validation rule should not be performed. No validation rules have default values. For list types, validation will be performed on each item on the list. A single invalid item will reject the entire list. ### option.validation.variants optional An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) that specify valid values for this option. If `variants` is specified, the value for this option must be one of the entries in `variants`. This is usually used to construct an enum. ```toml theme={null} validation.variants = [1, 2, 3] ``` ### option.validation.min optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the minimum allowed value for this option. ```toml theme={null} validation.min = 0 ``` ### option.validation.max optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the maximum allowed value for this option. ```toml theme={null} validation.max = 100 ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` # i64 option type Source: https://docs.coralos.ai/reference/agent/tables/options/i64 A . Integers should use the [environment transport](#environment-transport) as they are never large enough to use the [filesystem transport](#filesystem-transport). s have a minimum value of and a maximum value of . This range must be respected in values given for this option and values specified as defaults or for validation. | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | | (binary, big-endian) | (utf8) | ## Full example ```toml theme={null} [options.EXAMPLE_I64_OPTION] type = "i64" required = false default = 50000 display.label = "Example i64 Option" display.description = "This is an example i64 option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 25000, 50000, 75000, 100000] validation.min = 0 validation.max = 100000 ``` ```toml theme={null} [options.EXAMPLE_I64_OPTION] type = "list[i64]" required = false default = [0, 50000, 100000] display.label = "Example i64 List Option" display.description = "This is an example i64 list option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 25000, 50000, 75000, 100000] validation.min = 0 validation.max = 100000 ``` ## option.type required ```toml theme={null} type = "i64" ``` ```toml theme={null} type = "list[i64]" ``` ## option.default optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = 1000 ``` An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) specifying the default values for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = [1000, 2000, 3000] ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.validation The server performs option validation before running an agent. The Coral server will never launch an agent with option values that do not pass the validation rules given for an option. The absence of a validation rule indicates that the absent validation rule should not be performed. No validation rules have default values. For list types, validation will be performed on each item on the list. A single invalid item will reject the entire list. ### option.validation.variants optional An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) that specify valid values for this option. If `variants` is specified, the value for this option must be one of the entries in `variants`. This is usually used to construct an enum. ```toml theme={null} validation.variants = [1, 2, 3] ``` ### option.validation.min optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the minimum allowed value for this option. ```toml theme={null} validation.min = 0 ``` ### option.validation.max optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the maximum allowed value for this option. ```toml theme={null} validation.max = 100 ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` # i8 option type Source: https://docs.coralos.ai/reference/agent/tables/options/i8 A . Integers should use the [environment transport](#environment-transport) as they are never large enough to use the [filesystem transport](#filesystem-transport). s have a minimum value of and a maximum value of . This range must be respected in values given for this option and values specified as defaults or for validation. | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | | (binary, big-endian) | (utf8) | ## Full example ```toml theme={null} [options.EXAMPLE_I8_OPTION] type = "i8" required = false default = 50 display.label = "Example i8 Option" display.description = "This is an example i8 option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 25, 50, 75, 100] validation.min = 0 validation.max = 100 ``` ```toml theme={null} [options.EXAMPLE_I8_OPTION] type = "list[i8]" required = false default = [0, 50, 100] display.label = "Example i8 List Option" display.description = "This is an example i8 list option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 25, 50, 75, 100] validation.min = 0 validation.max = 100 ``` ## option.type required ```toml theme={null} type = "i8" ``` ```toml theme={null} type = "list[i8]" ``` ## option.default optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = 1000 ``` An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) specifying the default values for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = [1000, 2000, 3000] ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.validation The server performs option validation before running an agent. The Coral server will never launch an agent with option values that do not pass the validation rules given for an option. The absence of a validation rule indicates that the absent validation rule should not be performed. No validation rules have default values. For list types, validation will be performed on each item on the list. A single invalid item will reject the entire list. ### option.validation.variants optional An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) that specify valid values for this option. If `variants` is specified, the value for this option must be one of the entries in `variants`. This is usually used to construct an enum. ```toml theme={null} validation.variants = [1, 2, 3] ``` ### option.validation.min optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the minimum allowed value for this option. ```toml theme={null} validation.min = 0 ``` ### option.validation.max optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the maximum allowed value for this option. ```toml theme={null} validation.max = 100 ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` # string option type Source: https://docs.coralos.ai/reference/agent/tables/options/string A string option. If you expect the value for your string to be large, it should use the [filesystem transport](/reference/agent/tables/options/string#filesystem-transport). | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | `my option value` | `my option value` (utf-8) | `my option value`, (utf-8) | ## Full example ```toml theme={null} [options.EXAMPLE_STRING_OPTION] type = "string" required = false default = "the default value of my string" secret = false base64 = false display.label = "Example String Option" display.description = "This is an example string option." display.group = "Example Group" display.multiline = true # If variants are defined, min_length/max_length should not be defined # validation.variants = ["value1", "value2", "value3"] validation.min_length = 10 validation.max_length = 100 ``` ```toml theme={null} [options.EXAMPLE_STRING_OPTION] type = "list[string]" required = false default = ["default value 1", "default value 2"] secret = false base64 = true display.label = "Example String List Option" display.description = "This is an example string list option." display.group = "Example Group" display.multiline = true # If variants are defined, min_length/max_length should not be defined # validation.variants = ["value1", "value2", "value3"] validation.min_length = 1 validation.max_length = 10 ``` ## option.type required ```toml theme={null} type = "string" ``` ```toml theme={null} type = "list[string]" ``` ## option.default optional A [PotentialStringReference](/reference/types/potential-string-reference) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = "the default value of my string" ``` An [array](https://toml.io/en/v1.1.0#array) of [PotentialStringReferences](/reference/types/potential-string-reference) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = ["default value 1", "default value 2"] ``` ## option.secret default `false`
optional A [boolean](https://toml.io/en/v1.1.0#boolean) specifying whether the value for this option should be treated as a secret. Secret values are censored in configuration displays and the server's option-value log messages. Agent stdout/stderr is not automatically redacted. API keys or other sensitive values should be marked as secret. ```toml theme={null} secret = true ``` ## option.base64 default `false`
optional A [boolean](https://toml.io/en/v1.1.0#boolean) specifying whether the value for this option should be sent to the agent as a base64 encoded string. If the option is of type `list[string]`, and `transport` is either `env` or unspecified, base64 encoding should be abled to avoid confusing option values with the list seperating character: `,` ```toml theme={null} base64 = true ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.validation The server performs option validation before running an agent. The Coral server will never launch an agent with option values that do not pass the validation rules given for an option. The absence of a validation rule indicates that the absent validation rule should not be performed. No validation rules have default values. For list types, validation will be performed on each item on the list. A single invalid item will reject the entire list. ### option.validation.variants optional An [array](https://toml.io/en/v1.1.0#array) of [string literals](https://toml.io/en/v1.1.0#string) that specify valid values for this option. If `variants` is specified, the value for this option must be one of the entries in `variants`. This is usually used to construct an enum. ```toml theme={null} validation.variants = ["value1", "value2", "value3"] ``` ### option.validation.min\_length optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the minimum number of UTF-8 characters that must appear in string value. ```toml theme={null} validation.min_length = 10 ``` ### option.validation.max\_length optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the maximum number of UTF-8 characters that must appear in the string value. ```toml theme={null} validation.max_length = 100 ``` ### option.validation.regex optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a [regex pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) that the option value must match fully. ```toml theme={null} validation.regex = "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$" ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` ### option.display.multiline default `false`
optional A [boolean](https://toml.io/en/v1.1.0#boolean) specifying whether Coral console should create a text field for this option that allows multiple lines. This is useful for prompts or other large texts. ```toml theme={null} display.multiline = true ``` # u16 option type Source: https://docs.coralos.ai/reference/agent/tables/options/u16 A . Integers should use the [environment transport](#environment-transport) as they are never large enough to use the [filesystem transport](#filesystem-transport). s have a minimum value of and a maximum value of . This range must be respected in values given for this option and values specified as defaults or for validation. | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | | (binary, big-endian) | (utf8) | ## Full example ```toml theme={null} [options.EXAMPLE_U16_OPTION] type = "u16" required = false default = 500 display.label = "Example u16 Option" display.description = "This is an example u16 option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 250, 500, 750, 1000] validation.min = 0 validation.max = 1000 ``` ```toml theme={null} [options.EXAMPLE_U16_OPTION] type = "list[u16]" required = false default = [0, 500, 1000] display.label = "Example u16 List Option" display.description = "This is an example u16 list option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 250, 500, 750, 1000] validation.min = 0 validation.max = 1000 ``` ## option.type required ```toml theme={null} type = "u16" ``` ```toml theme={null} type = "list[u16]" ``` ## option.default optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = 1000 ``` An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) specifying the default values for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = [1000, 2000, 3000] ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.validation The server performs option validation before running an agent. The Coral server will never launch an agent with option values that do not pass the validation rules given for an option. The absence of a validation rule indicates that the absent validation rule should not be performed. No validation rules have default values. For list types, validation will be performed on each item on the list. A single invalid item will reject the entire list. ### option.validation.variants optional An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) that specify valid values for this option. If `variants` is specified, the value for this option must be one of the entries in `variants`. This is usually used to construct an enum. ```toml theme={null} validation.variants = [1, 2, 3] ``` ### option.validation.min optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the minimum allowed value for this option. ```toml theme={null} validation.min = 0 ``` ### option.validation.max optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the maximum allowed value for this option. ```toml theme={null} validation.max = 100 ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` # u32 option type Source: https://docs.coralos.ai/reference/agent/tables/options/u32 A . Integers should use the [environment transport](#environment-transport) as they are never large enough to use the [filesystem transport](#filesystem-transport). s have a minimum value of and a maximum value of . This range must be respected in values given for this option and values specified as defaults or for validation. | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | | (binary, big-endian) | (utf8) | ## Full example ```toml theme={null} [options.EXAMPLE_U32_OPTION] type = "u32" required = false default = 5000 display.label = "Example u32 Option" display.description = "This is an example u32 option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 2500, 5000, 7500, 10000] validation.min = 0 validation.max = 10000 ``` ```toml theme={null} [options.EXAMPLE_U32_OPTION] type = "list[u32]" required = false default = [0, 5000, 10000] display.label = "Example u32 List Option" display.description = "This is an example u32 list option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 2500, 5000, 7500, 10000] validation.min = 0 validation.max = 10000 ``` ## option.type required ```toml theme={null} type = "u32" ``` ```toml theme={null} type = "list[u32]" ``` ## option.default optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = 1000 ``` An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) specifying the default values for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = [1000, 2000, 3000] ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.validation The server performs option validation before running an agent. The Coral server will never launch an agent with option values that do not pass the validation rules given for an option. The absence of a validation rule indicates that the absent validation rule should not be performed. No validation rules have default values. For list types, validation will be performed on each item on the list. A single invalid item will reject the entire list. ### option.validation.variants optional An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) that specify valid values for this option. If `variants` is specified, the value for this option must be one of the entries in `variants`. This is usually used to construct an enum. ```toml theme={null} validation.variants = [1, 2, 3] ``` ### option.validation.min optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the minimum allowed value for this option. ```toml theme={null} validation.min = 0 ``` ### option.validation.max optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the maximum allowed value for this option. ```toml theme={null} validation.max = 100 ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` # u64 option type Source: https://docs.coralos.ai/reference/agent/tables/options/u64 **64bit unsigned integers must be represented as strings**! This is due to a limitation in JSON/JavaScript A . Integers should use the [environment transport](#environment-transport) as they are never large enough to use the [filesystem transport](#filesystem-transport). s have a minimum value of and a maximum value of . This range must be respected in values given for this option and values specified as defaults or for validation. | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | | (binary, big-endian) | (utf8) | ## Full example ```toml theme={null} [options.EXAMPLE_U64_OPTION] type = "u64" required = false default = "50000" display.label = "Example u64 Option" display.description = "This is an example u64 option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 25000, 50000, 75000, 100000] validation.min = "0" validation.max = "100000" ``` ```toml theme={null} [options.EXAMPLE_U64_OPTION] type = "list[u64]" required = false default = ["0", "50000", "100000"] display.label = "Example u64 List Option" display.description = "This is an example u64 list option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 25000, 50000, 75000, 100000] validation.min = "0" validation.max = "100000" ``` ## option.type required ```toml theme={null} type = "u64" ``` ```toml theme={null} type = "list[u64]" ``` ## option.default optional A [string](https://toml.io/en/v1.1.0#string) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = "1000" ``` An [array](https://toml.io/en/v1.1.0#array) of [strings](https://toml.io/en/v1.1.0#strings) specifying the default values for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = ["1000", "2000", "3000"] ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.validation The server performs option validation before running an agent. The Coral server will never launch an agent with option values that do not pass the validation rules given for an option. The absence of a validation rule indicates that the absent validation rule should not be performed. No validation rules have default values. For list types, validation will be performed on each item on the list. A single invalid item will reject the entire list. ### option.validation.variants optional An [array](https://toml.io/en/v1.1.0#array) of [strings](https://toml.io/en/v1.1.0#string) that specify valid values for this option. If `variants` is specified, the value for this option must be one of the entries in `variants`. This is usually used to construct an enum. ```toml theme={null} validation.variants = ["1", "2", "3"] ``` ### option.validation.min optional A [string](https://toml.io/en/v1.1.0#string) specifying the minimum allowed value for this option. ```toml theme={null} validation.min = "0" ``` ### option.validation.max optional A [string](https://toml.io/en/v1.1.0#string) specifying the maximum allowed value for this option. ```toml theme={null} validation.max = "100" ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` # u8 option type Source: https://docs.coralos.ai/reference/agent/tables/options/u8 A . Integers should use the [environment transport](#environment-transport) as they are never large enough to use the [filesystem transport](#filesystem-transport). s have a minimum value of and a maximum value of . This range must be respected in values given for this option and values specified as defaults or for validation. | Option value | `transport = "fs"` | `transport = "env"` | | - | - | - | | | (binary, big-endian) | (utf8) | ## Full example ```toml theme={null} [options.EXAMPLE_U8_OPTION] type = "u8" required = false default = 50 display.label = "Example u8 Option" display.description = "This is an example u8 option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 25, 50, 75, 100] validation.min = 0 validation.max = 100 ``` ```toml theme={null} [options.EXAMPLE_U8_OPTION] type = "list[u8]" required = false default = [0, 50, 100] display.label = "Example u8 List Option" display.description = "This is an example u8 list option." display.group = "Example Group" # If variants are defined, min/max should not be defined # validation.variants = [0, 25, 50, 75, 100] validation.min = 0 validation.max = 100 ``` ## option.type required ```toml theme={null} type = "u8" ``` ```toml theme={null} type = "list[u8]" ``` ## option.default optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the default value for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = 1000 ``` An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) specifying the default values for this option. If this is specified, setting `required = true` will have no effect. ```toml theme={null} default = [1000, 2000, 3000] ``` ## option.required default `false`
optional If `required = true` this option is **not** optional and must be specified. Setting `required = true` for an option that has a default value has no effect. ```toml theme={null} required = true ``` ## option.validation The server performs option validation before running an agent. The Coral server will never launch an agent with option values that do not pass the validation rules given for an option. The absence of a validation rule indicates that the absent validation rule should not be performed. No validation rules have default values. For list types, validation will be performed on each item on the list. A single invalid item will reject the entire list. ### option.validation.variants optional An [array](https://toml.io/en/v1.1.0#array) of [integers](https://toml.io/en/v1.1.0#integer) that specify valid values for this option. If `variants` is specified, the value for this option must be one of the entries in `variants`. This is usually used to construct an enum. ```toml theme={null} validation.variants = [1, 2, 3] ``` ### option.validation.min optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the minimum allowed value for this option. ```toml theme={null} validation.min = 0 ``` ### option.validation.max optional An [integer](https://toml.io/en/v1.1.0#integer) specifying the maximum allowed value for this option. ```toml theme={null} validation.max = 100 ``` ## option.transport default `env`
optional Controls how the option value is sent to the agent. ### Environment transport ```toml theme={null} transport = "env" ``` The environment transport will *send* the option value to the agent via an environment variable. The name of the environment variable will match the option name, and the value will be encoded in UTF-8. For lists, multiple values will be sent delimited by a comma `,`. It is recommended to use `option.base64 = true` when there is a chance the value will contain a comma. ### Filesystem transport ```toml theme={null} transport = "fs" ``` The filesystem transport will *send* the option value to the agent via a file. An environment variable matching the name of this option will be *sent* to the agent, the value of the environment variable will be the path to the file that contains the value for the option. For lists, multiple files will be created. A list of paths will be provided in the environment variable, delimited by either: * `;` on Windows * `:` on Unix-like operating systems ## option.display Display options are used to configure how the option should render in the Coral console. They may also be used in other third-party interfaces. ### option.display.label optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the label for this option. Coral console will display this label instead of the option's name if it is specified. ```toml theme={null} display.label = "My option" ``` ### option.display.description optional A [string literal](https://toml.io/en/v1.1.0#string) specifying a description for this option. The description will appear as a tooltip for this option in the Coral console. ```toml theme={null} display.description = "My option is used for ..." ``` ### option.display.group optional A [string literal](https://toml.io/en/v1.1.0#string) specifying the group that this option belongs to. Options with the same group will appear grouped in the Coral console. ```toml theme={null} display.group = "Prompts" ``` # Docker runtime Source: https://docs.coralos.ai/reference/agent/tables/runtimes/docker In Coral, (Docker) containers are the preferred production execution environment for Coral agents. The Docker runtime is a way of configuring the Coral server to run your agent using a Docker image. Running Docker agents on your Coral server may require additional configuration, see [the Docker config](/reference/server/docker) for more information. If you are running the Coral server using Docker, you must set up [Docker in Docker](/guides/production/docker-in-docker) # Full example ```toml theme={null} [runtimes.docker] image = "myusername/myagent" command = ["--custom-command", "123"] transport = "streamable_http" # default value ``` # Environment ### Standard streams Timestamps and log levels are prefixed by the Coral server, the agent should not print these. * Standard output will be printed to the agent’s log at an INFO level. * Standard error will be printed to the agent's log at a WARN level. * Standard input is not used ### Coral environment variables #### `CORAL_CONNECTION_URL` The URL of the MCP server that this agent must connect to, either SSE or Streamable HTTP depending on the value given for [runtimes..transport](#transport). This URL will change every time the agent is launched. This URL contains the [agent secret](#coral_agent_secret) and should not be printed or shared. The value of this should also not be given to an LLM. #### `CORAL_RUNTIME_ID` Always set to . #### `CORAL_AGENT_ID` The unique name provided for this agent in [GraphAgentRequest.name](/api-reference/models/GraphAgentRequest#name). #### `CORAL_AGENT_SECRET` A unique secret generated for this agent. This secret is used to authenticate communications between the agent and the Coral server. This secret should not be printed, shared or given to an LLM. #### `CORAL_SESSION_ID` The unique ID of the session that this agent belongs to. This ID is generated by the Coral server and is used uniquely to identify a session. This ID should not be printed, shared or given to an LLM. #### `CORAL_API_URL` The base URL of the Coral server. Agent RPC endpoints under `/api/v1/agent-rpc` use the [agent secret](#coral_agent_secret) as a bearer token. Application REST endpoints use server auth keys instead; an agent secret does not grant application API access. ### Optional Coral environment variables #### `CORAL_PROMPT_SYSTEM` If the session that launched this agent defines a [systemPrompt](/api-reference/models/GraphAgentRequest#schema-system-prompt), it will be set to this environment variable. If not, this variable will not be set. #### LLM proxy variables A resolved proxy request named `MAIN` provides `CORAL_PROXY_URL_MAIN`, `CORAL_PROXY_FORMAT_MAIN`, and `CORAL_PROXY_MODEL_MAIN`. See [AgentLlmProxyRequest](/reference/types/agent-llm-proxy-request). ### Other environment variables * An environment variable for every defined [agent option](/reference/agent/tables/options) * Environment variables configured in the Docker image (*not* including other environment variables the server was launched with) * All environment variables configured in the Coral server's [debug.additionalDockerEnvironment](/reference/server/debug#additional-docker-environment) configuration field # Configuration ### runtimes.docker.image required **Example** ```toml theme={null} [runtimes.docker] image = "myusername/myagent" ``` A [string](https://toml.io/en/v1.1.0#string) representing the Docker image name to run for this agent. If no tag is specified, the [version of the agent](/reference/agent/tables/agent#agent-version) will be used as a tag. It is recommended to **not** specify a tag in this field and allow the agent version to control which Docker image is used. ### runtimes.docker.command optional **Example** ```toml theme={null} [runtimes.docker] command = ["--custom-command", "123"] ``` An [array](https://toml.io/en/v1.1.0#array) of [strings](https://toml.io/en/v1.1.0#string) overriding the default command ran in the Docker container. Leave this field empty to use the command specified in the Docker image. ### runtimes.docker.transport default `streamable_http`
optional **Example** ```toml theme={null} [runtimes.docker] transport = "sse" ``` `sse` is deprecated and may be removed in a future release. A [string](https://toml.io/en/v1.1.0#string) controlling the value of the [CORAL\_CONNECTION\_URL](#coral_connection_url) Coral environment variable. If your agent requires a specific MCP transport protocol, it must be set here. Supported values: * `sse` * `streamable_http` # Executable runtime Source: https://docs.coralos.ai/reference/agent/tables/runtimes/executable Executable runtimes are not permitted on the Coral marketplace Executable runtimes can be configured to run an executable of your choice. This is a useful development runtime, allowing you to run your agent without containerizing it first. # Full example ```toml theme={null} [runtimes.executable] path = "python3" arguments = ["main.py"] transport = "streamable_http" # default value ``` ```toml theme={null} [runtimes.executable] path = "bun" arguments = ["run", "src/index.ts"] transport = "streamable_http" # default value ``` ```toml theme={null} [runtimes.executable] path = "cargo" arguments = ["run", "--release"] transport = "streamable_http" # default value ``` # Environment ### Standard streams Timestamps and log levels are prefixed by the Coral server, the agent should not print these. * Standard output will be printed to the agent’s log at an INFO level. * Standard error will be printed to the agent's log at a WARN level. * Standard input is not used ### Coral environment variables #### `CORAL_CONNECTION_URL` The URL of the MCP server that this agent must connect to, either SSE or Streamable HTTP depending on the value given for [runtimes..transport](#transport). This URL will change every time the agent is launched. This URL contains the [agent secret](#coral_agent_secret) and should not be printed or shared. The value of this should also not be given to an LLM. #### `CORAL_RUNTIME_ID` Always set to . #### `CORAL_AGENT_ID` The unique name provided for this agent in [GraphAgentRequest.name](/api-reference/models/GraphAgentRequest#name). #### `CORAL_AGENT_SECRET` A unique secret generated for this agent. This secret is used to authenticate communications between the agent and the Coral server. This secret should not be printed, shared or given to an LLM. #### `CORAL_SESSION_ID` The unique ID of the session that this agent belongs to. This ID is generated by the Coral server and is used uniquely to identify a session. This ID should not be printed, shared or given to an LLM. #### `CORAL_API_URL` The base URL of the Coral server. Agent RPC endpoints under `/api/v1/agent-rpc` use the [agent secret](#coral_agent_secret) as a bearer token. Application REST endpoints use server auth keys instead; an agent secret does not grant application API access. ### Optional Coral environment variables #### `CORAL_PROMPT_SYSTEM` If the session that launched this agent defines a [systemPrompt](/api-reference/models/GraphAgentRequest#schema-system-prompt), it will be set to this environment variable. If not, this variable will not be set. #### LLM proxy variables A resolved proxy request named `MAIN` provides `CORAL_PROXY_URL_MAIN`, `CORAL_PROXY_FORMAT_MAIN`, and `CORAL_PROXY_MODEL_MAIN`. See [AgentLlmProxyRequest](/reference/types/agent-llm-proxy-request). ### Other environment variables * An environment variable for every defined [agent option](/reference/agent/tables/options) * All the environment variables the Coral server was launched with * All environment variables configured in the Coral server's [debug.additionalExecutableEnvironment](/reference/server/debug#additional-executable-environment) configuration field # Configuration ### runtimes.executable.path required **Example** ```toml theme={null} [runtimes.executable] path = "bootstrap" ``` Arguments cannot be provided in the path. All arguments must be provided via [runtimes.executable.arguments](#runtimes-executable-arguments) A [string](https://toml.io/en/v1.1.0#string) representing the path to the executable. This can be: * A name of an executable/script on your systems `PATH` environment variable * An executable, relative to the `coral-agent.toml` file * An absolute path to an executable/script **Requirements** * The executable path must be between 1 and 4096 characters long. On Windows, the Coral server will try to append the extensions: * `.exe` * `.cmd` * `.bat` To the executable path. If no files are found with these extensions, it will fallback to the specified path with no extension. This is a useful feature when developing an agent that requires a bootstrap script. Consider the following structure: The example will execute the `bootstrap` file (use a [shebang](https://en.wikipedia.org/wiki/Shebang_\(Unix\)) in this file) on Unix and the `bootstrap.bat` on Windows. ### runtimes.executable.arguments optional An [array](https://toml.io/en/v1.1.0#array) of [strings](https://toml.io/en/v1.1.0#string) denoting the arguments to pass to [runtimes.executable.path](#runtimes-executable-path) **Example** ```toml theme={null} [runtimes.executable] path = "npm" arguments = ["run", "start"] ``` **Requirements** * No more than 1024 arguments can be provided. * The total size of all arguments must not exceed 2 KiB ### runtimes.executable.transport default `streamable_http`
optional **Example** ```toml theme={null} [runtimes.executable] transport = "sse" ``` `sse` is deprecated and may be removed in a future release. A [string](https://toml.io/en/v1.1.0#string) controlling the value of the [CORAL\_CONNECTION\_URL](#coral_connection_url) Coral environment variable. If your agent requires a specific MCP transport protocol, it must be set here. Supported values: * `sse` * `streamable_http` # Prototype runtime Source: https://docs.coralos.ai/reference/agent/tables/runtimes/prototype The [Koog template](/guides/quickstart#koog-template) is the main path for writing agents and a reference for implementations in other frameworks. Write agent code when you need custom context management, memory, control flow, or execution behavior. Use the prototype runtime when you already know a simple prompt-and-tool loop is sufficient. It runs a Koog agent inside Coral Server with an LLM, Coral tools, and optional remote MCP tools, without a separate executable or container. ## Complete agent definition Save this as `coral-agent.toml` and add its directory to `registry.localAgents` (or use `coralizer link .`): ```toml theme={null} edition = 5 [agent] name = "report-writer" version = "1.0.0" description = "Writes reports using the tools supplied by the application" summary = "A configurable report writer" readme = "A prototype agent for application-provided reporting tasks." license = { type = "spdx", expression = "MIT" } [options.TASK] type = "string" required = true display.description = "The report to produce" [runtimes.prototype] proxy = "MAIN" iterations = 20 delay = 0 prompts.loop.initial.extra = { type = "option", name = "TASK" } [[llm.proxies]] name = "MAIN" format.type = "OpenAI" models = ["gpt-4.1"] ``` Configure a matching [server LLM provider](/reference/server/llm-proxy#providers), or supply a Coral Cloud API key. Create sessions with `provider: { "type": "local", "runtime": "prototype" }`, provide `options.TASK`, and grant application tools through `customToolAccess`. ## Runtime settings | Field | Default | Meaning | | - | - | - | | `proxy` | Required | Name of a request in `llm.proxies`. | | `client` | Inferred from proxy format | `"openai"`, `"anthropic"`, `"deepseek"`, or explicit `"openrouter"`. | | `iterations` | `20` | Positive number of LLM/tool iterations. | | `delay` | `0` | Nonnegative delay in milliseconds before iterations after the first. | | `volatile` | `false` | If true, an iteration error stops the runtime; otherwise the error is logged and later iterations continue. | | `tools` | Empty list | Additional HTTP MCP servers. Coral's own tools are included automatically. | Model selection is constrained by the selected Koog client's known model catalogue. A proxy accepting an arbitrary model name does not guarantee the prototype client supports that model. `proxy` and prompt values accept an inline string or `{ type = "option", name = "OPTION_NAME" }`. `iterations` and `delay` accept an inline integer or an integer option reference. Option references must name compatible options defined on this agent. ## Prompts and resources The runtime starts with a system prompt and an initial user message. Later iterations receive the follow-up message while retaining the conversation. Prompt fields are: * `prompts.system.base` and `prompts.system.extra` * `prompts.loop.initial.base` and `prompts.loop.initial.extra` * `prompts.loop.followup` The default system prompt includes `coral://instruction` and `coral://state`. These placeholders are refreshed before each LLM call. When replacing `prompts.system.base`, include these placeholders to retain that context. Supplying `systemPrompt` on the session's agent request does not automatically append it to prototype prompts; configure the prototype's prompt fields and options explicitly. The runtime requests tool calls from the LLM and executes those tools. Use an application-provided custom tool to return a report or request input; plain assistant text is not an application result callback. ## Additional MCP servers ```toml theme={null} [[runtimes.prototype.tools]] type = "mcp_streamable_http" url = "https://example.com/mcp" auth.type = "bearer" auth.token = { type = "option", name = "MCP_TOKEN" } [options.MCP_TOKEN] type = "string" required = true secret = true ``` Supported transports are `mcp_streamable_http` and legacy `mcp_sse`; stdio subprocess MCP servers are not supported here. Authentication supports `none`, `bearer` with `token`, and `authorization_header` with `header`. Configure HTTPS endpoints. Prototype agents share the server process. Use Docker when you need custom agent code or container isolation. Bound execution with a session TTL as well as the iteration limit. # Server configuration Source: https://docs.coralos.ai/reference/server # Configuration tables The Coral server is configured using configuration tables. The following tables are available: | Table | Description | | - | - | | [authentication](/reference/server/auth) | Configure access to the Coral server | | [cache](/reference/server/cache) | File cache paths | | [cloud](/reference/server/cloud) | Coral Cloud integration | | [llm-proxy](/reference/server/llm-proxy) | LLM providers, limits, and retries | | [session](/reference/server/session) | Agent wait-tool timeout | | [console](/reference/server/console) | Configuration for the built-in Coral console | | [debug](/reference/server/debug) | Debugging configuration | | [docker](/reference/server/docker) | Docker runtime configuration | | [logging](/reference/server/logging) | Logging configuration | | [network](/reference/server/network) | Network configuration | | [registry](/reference/server/registry) | Agent registry configuration | # Setting configuration options Configuration options can be set through command-line arguments, environment variables, and a configuration file. Configuration options set in a higher priority method will override options set in a lower priority method. In order of priority, highest to lowest: ### 1. Command line Options can be specified via the command line. Depending on how the Coral server is started, the command line options may be specified in different ways, such as: ```bash title=Gradle theme={null} ./gradlew run --args="--auth.keys=dev" ``` The syntax for specifying command line options is `--.=`, `keys` can be specified in: * lower case * camel case * snake case ### 2. Environment variables Use two underscores between the table and the field: `NETWORK__BIND_PORT=5555` sets `network.bindPort`. Single underscores separate words inside a field. See the [environment variable reference](/configuration/environment-variables). ### 3. Configuration file The Coral server will load a [TOML](https://toml.io/) configuration file from a path specified by the `CONFIG_FILE_PATH` environment variable. There is no default location for the configuration file; if the environment variable is not set, no configuration file will be loaded from disk. Custom builds can also bundle an optional `/config.toml` resource; the standard build uses code defaults. **Example:** ```bash title="Environment variables" theme={null} CONFIG_FILE_PATH=/path/to/config.toml ``` ```toml title=/path/to/config.toml theme={null} [auth] keys = ["my access key"] ``` If `CONFIG_FILE_PATH` is set, it must point to a valid and accessible configuration file. Pointing to an invalid configuration file will cause an error launching the Coral server. # Authentication Source: https://docs.coralos.ai/reference/server/auth # Keys default empty list
Auth keys are used to authenticate requests made to the Coral server. These keys allow full access to the Coral server and its APIs. The keys should be kept secret. Using the Coral console also requires a key. There are no keys set by default. At least one key must be set to effectively use the Coral server. # File cache Source: https://docs.coralos.ai/reference/server/cache The cache configuration contains filesystem paths: | Field | Default | | - | - | | `cache.root` | `${user.home}/.coral` | | `cache.index` | `${cache.root}/index` | | `cache.agent` | `${cache.root}/agent` | # Cloud Source: https://docs.coralos.ai/reference/server/cloud # API key default `undefined`
Specifying a [Coral Cloud API key](https://coralcloud.ai/account) enables Cloud-powered features in Coral Server and Coral Console. For a self-hosted server, this is a convenience option for automatically configuring supported LLM providers and models. Your server and console continue to run on your own infrastructure. You can also [configure your own provider keys](/reference/server/llm-proxy#your-own-provider-keys) directly. # Coral Console Source: https://docs.coralos.ai/reference/server/console # Enable console default `true`
If this is set to `false`, the Coral server will not serve the Coral console at `/ui/console`. Consider disabling this in production environments. # Cache path default `${HOME}/.coral/console`
The path that the Coral console will be downloaded to. Note: this directory should not contain anything but Coral console files. This directory may be deleted by the Coral server when the Coral console is updated. The path must resolve inside `${HOME}/.coral`; a path outside that directory prevents the console from starting. # Console release URL default `https://github.com/Coral-Protocol/console/releases/download`
The path that the Coral console versions will be downloaded from. This should only be changed if using a fork of the Coral console. # Console release version default stable Console version for given Coral server version
The name of the Coral console version to download. This can be changed to use beta versions of the Coral console. Not all Coral console versions are compatible with all Coral server versions. If you change this, ensure that the selected Coral console version remains compatible when performing Coral server upgrades. # Bundle name default `coral-console_${consoleReleaseVersion}.zip`
The name of the bundle to download. Note that if this is changed, the [console release version](#console-release-version) will have no effect. # Delete old versions default `false`
If this is `true`, the Coral server will delete old versions of the Coral console when it starts. # Always download default `false`
If this is true, the Coral server will always download the latest version of the Coral console even if it is already downloaded. This can be used if a forked version of the Coral console opts to update an existing version. # Debug Source: https://docs.coralos.ai/reference/server/debug # Additional Docker environment variables default empty map
This configuration option cannot be specified via the command line. ```toml theme={null} [debug.additional_docker_environment] MY_VAR_1 = "my value" MY_VAR_2 = "my other value" ``` A map of additional environment variables that will be set and passed to agents that use the [Docker runtime](/reference/agent/tables/runtimes/docker). These variables will not overwrite Coral environment variables or options. # Additional Executable environment variables default empty map
This configuration option cannot be specified via the command line. ```toml theme={null} [debug.additional_executable_environment] MY_VAR_1 = "my value" MY_VAR_2 = "my other value" ``` A map of additional environment variables that will be set and passed to agents that use the [Executable runtime](/reference/agent/tables/runtimes/executable). These variables will not overwrite Coral environment variables or options. # Docker Source: https://docs.coralos.ai/reference/server/docker # Socket default see below:
The default value for this is calculated in the following order, taking the first value that is specified: 1. The JVM system property `CORAL_DOCKER_SOCKET` 2. The JVM system property `docker.host` 3. The environment variable `DOCKER_SOCKET` 4. The JVM system property `docker.socket` 5. `npipe:////./pipe/docker_engine`, but only if the OS is Windows 6. `unix://$HOME/.colima/default/docker.sock` if it exists 7. `unix:///var/run/docker.sock` The Docker socket that Coral will execute Docker runtimes via. This value should almost always be left as the default. # Address default see below:
The default value for Windows is always `host.docker.internal`. On other systems, the default is `host.docker.internal` when `$HOME/.colima/default/docker.sock` exists, and `172.17.0.1` otherwise. The address that Docker runtimes will use to communicate with the Coral server. Different container runtimes may use different values to communicate with the host; if a specific container runtime is used that requires a different address, it must be specified here. This must also be specified if the container runtime is on another machine; in which case this address should be the public address of the machine running the Coral server. # Response timeout default `30`
The number of seconds before the Coral server times out when trying to communicate with the container runtime. # Connection timeout default `30`
The number of seconds before the Coral server times out when trying to connect to the container runtime. Note that this timeout will always be reached if the container runtime is not running. # Max connections default `1024`
The maximum number of connections that the Coral server can make to containers. Each agent running using a Docker runtime requires one connection. This value should be large enough to accommodate the number of agents that will be running on the Coral server at any one time. # Container path separator default `:`
The character that is used for separating multiple paths in a running container. This must be changed to `;` when running Windows containers. This should **NOT** be set to `;` if running Linux containers on a Windows host. # Container name separator default `/`
The character that is used to separate path names on a running container. This can be changed to `\` when running Windows containers. Note that this should **NOT** be set to `\` if running Linux containers on a Windows host. # Container temporary directory default `/tmp`
The directory on a running container that is used for temporary files. # LLM proxy Source: https://docs.coralos.ai/reference/server/llm-proxy # Retry attempts default `0`
If configured to be a value greater than 0, failed proxied LLM requests made to the Coral Server will be retried up to the specified number of times. The delay between retries is exponential, see: * [Retry base delay](#retry-base-delay) * [Retry delay exponent](#retry-delay-exponent) * [Retry attempts](#retry-attempts) * [Retry max delay](#retry-max-delay). # Retry base delay default `1s`
See [here](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.time/-duration/-companion/parse.html) for more information on the duration format. If an LLM proxy request fails to reach the configured LLM provider, the request may be retried. This value serves as the initial delay for the first retry, and, for every subsequent retry, the delay will be increased exponentially by [Retry delay exponent](#retry-delay-exponent). With the following configuration: * [Retry base delay](#retry-base-delay) of `1s` * [Retry delay exponent](#retry-delay-exponent) of `2.0` * [Retry max delay](#retry-max-delay) of `10s` Delays between retries will be: 1. `1s` 2. `2s` 3. `4s` 4. `8s` 5. `10s` # Retry delay exponent default `2.0`
The exponent applied to [Retry base delay](#retry-base-delay) between retries. The exponent is applied after the first retry. The value must be a floating point number. # Retry max delay default `10s`
See [here](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.time/-duration/-companion/parse.html) for more information on the duration format. The maximum delay between retries. This caps the exponential delay configured with [Retry base delay](#retry-base-delay) and [Retry delay exponent](#retry-delay-exponent). # Max request size default `20MiB`
A [ByteSize](/reference/types/byte-size) value representing the maximum size of a request that can be proxied to an LLM provider. Requests made larger than this size will be rejected. # Max response size default `80MiB`
A [ByteSize](/reference/types/byte-size) value representing the maximum size of a response that can be read from a proxied LLM provider. Responses larger than this size will be rejected, and the LLM request will receive an error. # Max stream size default `80MiB`
A [ByteSize](/reference/types/byte-size) value representing the maximum size of a response that can be read from a proxied LLM provider via an SSE stream. This value is cumulative across the lifetime of the SSE stream. Responses larger than this size will be rejected, and the LLM request will receive an error. # Providers default empty array
Configure your own provider keys below, or use the [Coral Cloud LLM proxy](#coral-cloud-llm-proxy) as a convenience option. Both work with a self-hosted Coral Server and Coral Console. ## Your own provider keys LLM Proxy providers cannot be configured from the command line. ```toml theme={null} [[llm-proxy.providers]] name = "My OpenAI Provider" format.type = "OpenAI" api_key = "..." base_url = "https://api.openai.com" models = ["gpt-4.1-mini", "gpt-5-mini"] [[llm-proxy.providers]] name = "Default Anthropic" format.type = "Anthropic" api_key = "..." base_url = "https://api.anthropic.com" models = ["claude-opus-4-6", "claude-sonnet-4-0"] ``` These base URLs assume clients that send the `/v1/...` path, including the built-in prototype OpenAI client. See [base URL composition](/reference/types/llm-proxy-provider-config#base_url) when using a different SDK. An array of [LlmProxyProviderConfig](/reference/types/llm-proxy-provider-config) objects. ## Coral Cloud LLM proxy Setting a [Coral Cloud API key](/reference/server/cloud#api-key) automatically configures supported Coral Cloud LLM providers and models: ```bash theme={null} ./gradlew run --args="--auth.keys=dev --cloud.api-key=coral..." ``` Your server and console remain self-hosted. This option routes model requests through Coral Cloud; it does not require using the Cloud-hosted server or console. # Logging Source: https://docs.coralos.ai/reference/server/logging # Log buffer size default `32768`
The maximum number of log entries to keep in memory. This buffer is used for all log messages, including those sent by agents. Note that the Coral console log view for an agent only applies a filter to the log buffer, so, if you desire 1000 log entries per agent, the buffer must be `1000` x `number of agents` + extra for system log entries. Consider adjusting this value only after you experience loss of log entries in the Coral console. # Max replay default `2048`
The maximum number of log entries that will be sent to a new subscriber. Note that opening a Coral console agent log view counts as a new subscription; this value caps the number of messages that appear in that view. # Console log level default `INFO`
The maximum log level that will be printed to the server's console. Valid values, in order of increasing verbosity: * `ERROR` * `WARN` * `INFO` * `DEBUG` * `TRACE` # File log level default `INFO`
The maximum log level that will be printed to the disk. Note [enable file logging](#enable-file-logging) must be true to write any messages to disk. Valid values, in order of increasing verbosity: * `ERROR` * `WARN` * `INFO` * `DEBUG` * `TRACE` # Enable file logging default `true`
If this is true, log messages will be written to a file on disk. The directory, number of log files, log file size and other file logging options are further configurable using: * [Log files directory](#log-files-directory) * [Log file name](#log-file-name) * [Log file name pattern](#log-file-pattern) * [Max history](#max-history) * [Log total size cap](#log-total-size-cap) * [Clear log files on server start](#clear-log-files-on-server-start) * [Max file size](#max-file-size) * [File log level](#file-log-level) # Log files directory default `${HOME}/.coral/logs`
The directory where log files will be written. Note that the full path to a given log file may be different from the value of this setting, see: * [Log file name](#log-file-name) * [Log file name pattern](#log-file-pattern) # Log file name default `${logFilesDirectory}/server.log`
The full path to the log file. Read more [here](https://logback.qos.ch/manual/appenders.html#fileAppenderFile). # Log file name pattern default `${logFilesDirectory}/archive/%d{yyyy/MM, aux}/%d{yyyy-MM-dd}.%i.log.gz`
The pattern for archived log files. Read more [here](https://logback.qos.ch/manual/appenders.html#tbrpFileNamePattern). # Max history default `12`
The maximum number of archived log files to keep. Read more [here](https://logback.qos.ch/manual/appenders.html#tbrpMaxHistory). # Log total size cap default `3GB`
The maximum total size of all archived log files. Read more [here](https://logback.qos.ch/manual/appenders.html#tbrpTotalSizeCap). # Clear log files on server start default `false`
If this is true, archived log files that are configured to be deleted will be deleted when the server starts. Read more [here](https://logback.qos.ch/manual/appenders.html#tbrpCleanHistoryOnStart). # Max file size default `10MB`
The maximum size of the current log file; when the current log file hits this size, the log file will be archived. Read more [here](https://logback.qos.ch/manual/appenders.html#maxFileSize). # Network Source: https://docs.coralos.ai/reference/server/network # Bind address default `0.0.0.0`
The IP address that the Coral server will bind to. The Coral server API will be available on this address. # External address default value of [bind address](#bind-address)
The remote IP address of the Coral server. This IP address is given to Coral agents. This is useful if the Coral agents are launched on separate machines, such as within a Kubernetes cluster. # Bind port default `5555`
The port that the Coral server will bind to. Only TCP traffic is used by the Coral server. In v1.5.0, command-line conversion of this unsigned value rejects ports above 32767. Configure higher ports as a numeric `bindPort` in `config.toml`; that file-based path supports them. # Allow any host default `false`
Controls the CORS policy for the Coral server API. This should only be set to `true` during development. # Webhook secret default v4 UUID
A secret used to sign webhook requests. Webhooks will contain a HmacSHA256 signature of the payload in the `X-Coral-Signature` header. This secret should be verified by the recipient of the webhook. # Custom tool secret default v4 UUID
A secret used to sign agent custom tool calls. Agent custom tool calls will contain a HmacSHA256 signature of the payload in the `X-Coral-Signature` header. This secret should be verified by the recipient of the webhook. # Registry Source: https://docs.coralos.ai/reference/server/registry # Local agents default empty list
A list of paths to agents on the local machine. Any agent included in this list will be available to the Coral server in the local agent registry source. Consider the following directory structure: Adding just `agent1` could be done with: ```toml theme={null} [registry] local_agents = ["/path/to/agents/agent1"] ``` Adding all agents (`agent1`, `agent2` and `agent3`) could be done with: ```toml theme={null} [registry] local_agents = ["/path/to/agents/*"] ``` Sometimes, you may want to use multiple wildcard paths, for example if you keep your agents in folders with versions: This can be facilitated with: ```toml theme={null} [registry] local_agents = ["/path/to/agents/*/*"] ``` The wildcard `*` is not permitted as part of a path segment, only as a full path segment.
Good ```toml theme={null} [registry] local_agents = ["/path/to/agents/*/*"] ``` Bad ```toml theme={null} [registry] local_agents = ["/path/to/agents*"] ``` # Include Coral home agents default `true`
If this is set to `true`, the following directories will be added to [local agents](#local-agents): * `${HOME}/.coral/agents/*/*` * `${HOME}/.coral/agents/*` * `${HOME}/.coral/agents/locallinked/*/*` It is recommended to use this configuration option instead of manually adding the above paths to [local agents](#local-agents). # Watch local agents default `true`
If this is set to true, modifications to local agents will be automatically detected and reloaded. Detected changes include: * Deletion of an agent * Modification of an agent * New agents (for example, those that match a path that uses a wildcard) It is possible due to a JVM limitation that changes to agents, especially those made programmatically, are not detected via this watch option. Consider setting [local agent rescan timer](#local-agent-rescan-timer) to a non-zero value. # Local agent rescan timer See [here](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.time/-duration/-companion/parse.html) for more information on the format. If this is set to a non-zero value, the Coral server will periodically rescan the local agent registry for changes. Scanning the filesystem can be expensive, especially if the [local agents](#local-agents) list contains many paths with wildcards. Consider setting this to a high value or disabling it entirely. # Include debug agents default `false`
If this is true, the Coral server [debug agents](/guides/debugging#built-in-debug-agents) will be available in the server's local agent registry source. # Include marketplace agents default `false`
If this is true, the Coral server will be able to directly use agents from the [Marketplace](/concepts/marketplace). # Session Source: https://docs.coralos.ai/reference/server/session ## Default wait timeout `session.defaultWaitTimeout` defaults to `60000` milliseconds. It controls the default timeout for agent wait tools. Client transport timeouts should leave enough time for the wait tool to return its normal timeout response. ```toml theme={null} [session] defaultWaitTimeout = 60000 ``` This is separate from a session's TTL and persistence settings, which are supplied per session through the [session API](/concepts/sessions). In v1.5.0, MCP wait tools pass their own `maxWaitMs` value (default and maximum: `60000`), so changing this server setting does not override those calls. Clients should set `maxWaitMs` below their transport timeout, leaving time for the tool to return its normal timeout response. # AgentLlmProxyRequest Source: https://docs.coralos.ai/reference/types/agent-llm-proxy-request An agent's request for an LLM proxy. An AgentLlmProxyRequest is a type used exclusively in the [llm.proxies](/reference/agent/tables/llm#llm-proxies) array to specify the requirement of an LLM proxy. In [Docker](/reference/agent/tables/runtimes/docker) and [Executable](/reference/agent/tables/runtimes/executable) runtimes, a resolved LLM proxy request sets `CORAL_PROXY_URL_`, `CORAL_PROXY_FORMAT_`, and `CORAL_PROXY_MODEL_`. For example, the request: ```toml theme={null} [[llm.proxies]] name = "MAIN" format.type = "OpenAI" models = ["gpt-5.3", "gpt-5.2", "gpt-5"] ``` Could produce the following environment variables: ```bash theme={null} # Should be used as the baseURL in LLM requests CORAL_PROXY_URL_MAIN=... CORAL_PROXY_FORMAT_MAIN=OpenAI CORAL_PROXY_MODEL_MAIN=gpt-5.2 ``` The server will not launch agents that it cannot resolve proxies for! ### name required ```toml theme={null} [[llm.proxies]] name = "MAIN" format.type = "OpenAI" ``` The name of the proxy request. **Requirements** * The name must be between 1 and 32 characters long. * The name must contain only uppercase alphanumeric characters and underscores. * The name must be unique. ### format.type required The LLM request format. Current supported types are: * `OpenAI` * `Anthropic` * `DeepSeek` ```toml theme={null} [[llm.proxies]] name = "MAIN" format.type = "Anthropic" ``` ### models required A list of models that this request will accept. Only one of the listed models will be used. **Requirements** * The name of a model must be between 1 and 128 characters long. * There must be 32 or fewer models listed. # ByteSize Source: https://docs.coralos.ai/reference/types/byte-size A type for describing a number of bytes. The ByteSize type is used when a configuration field requires a size in bytes. Sizes are specified by combining a [floating point number](https://toml.io/en/v1.1.0#float) with a [size unit](#available-size-units). For example, 10 KiB can be specified as an inline table: ```toml theme={null} size = { size = 10.0, unit = "KiB" } ``` Or as a string: ```toml theme={null} size = "10.0 KiB" ``` This will result in a size of 10,240 bytes. ### Available size units | Unit | Name | Size in Bytes | | - | - | - | | B | BYTE | 1 | | KiB | KIBIBYTE | 1,024 | | MiB | MEBIBYTE | 1,048,576 | | GiB | GIBIBYTE | 1,073,741,824 | | kB | KILOBYTE | 1,000 | | MB | MEGABYTE | 1,000,000 | | GB | GIGABYTE | 1,000,000,000 | The size will be rounded to the nearest byte. # LlmProxyProviderConfig Source: https://docs.coralos.ai/reference/types/llm-proxy-provider-config A definition for an LLM proxy provider. This type is only used in the [llm-proxy.providers](/reference/server/llm-proxy#providers) server config. Use this configuration with your own provider keys. For convenience, a [Coral Cloud API key](/reference/server/cloud#api-key) can automatically configure supported providers while your server and console remain self-hosted. Any agent that has defined [LLM proxy requests](/reference/types/agent-llm-proxy-request) requires the server to have a suitable LLM proxy provider configured for every request. ### name required The name of the LLM proxy provider. This must be unique. Application developers can request the usage of a specific LLM proxy provider by specifying this name in the [proxies map](/api-reference/models/GraphAgentRequest#schema-proxies). ### format.type required ```toml theme={null} [[llm-proxy.providers]] name = "My OpenAI Provider" format.type = "OpenAI" # ... ``` The LLM provider format. Current supported types are: * `OpenAI` * `Anthropic` * `DeepSeek` ### models optional ```toml theme={null} [[llm-proxy.providers]] name = "My OpenAI Provider" format.type = "OpenAI" models = ["gpt-4.1-mini", "gpt-5-mini"] allow_any_model = true # ... ``` An array of models that this provider supports. This may be omitted if [allow\_any\_model](#allow_any_model) is set to `true`. Note that if this is empty, the default value of [allow\_any\_model](#allow_any_model) is `true`. ### api\_key required ```toml theme={null} [[llm-proxy.providers]] name = "My OpenAI Provider" format.type = "OpenAI" api_key = "sk-..." # ... ``` The API key to use for this provider. ### base\_url required ```toml theme={null} [[llm-proxy.providers]] name = "My OpenAI Provider" format.type = "OpenAI" base_url = "https://api.openai.com" # ... ``` The base URL to use for this provider. Requests will be made to this URL with the path of the request appended. The proxy appends the agent's request path without removing or inserting a version prefix. Configure the provider base and the agent SDK's base URL together. For the built-in prototype runtime's OpenAI client (and the Koog template), requests contain `v1/chat/completions`; use `https://api.openai.com` as the provider base. Setting that provider base to `https://api.openai.com/v1` produces `/v1/v1/chat/completions`. An SDK that sends only `chat/completions` instead needs the provider base to include `/v1`, or the SDK base URL to add `/v1` after `CORAL_PROXY_URL_`. Confirm the actual upstream path when adapting a new client. The same rule applies to Anthropic's `/v1/messages` endpoint and other compatible providers. The `format.type` selects request authentication and usage parsing; it does not translate arbitrary provider APIs into OpenAI or Anthropic APIs. ### timeout default `10m`
optional ```toml theme={null} [[llm-proxy.providers]] name = "My OpenAI Provider" format.type = "OpenAI" timeout = "30s" # ... ``` See [here](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.time/-duration/-companion/parse.html) for more information on the duration format. A timeout for requests made to this provider. Slower providers may require a longer timeout. ### allow\_any\_model optional ```toml theme={null} [[llm-proxy.providers]] name = "My OpenAI Provider" format.type = "OpenAI" allow_any_model = true # ... ``` If `true`, this provider will match a request for any model that matches the specified [format](#format-type). This is useful for defining fallback providers that can handle many models, e.g., OpenRouter. Resolution of [AgentLlmProxyRequest](/reference/types/agent-llm-proxy-request) will prioritize providers that have explicitly specified a model over providers that allow any model. The default value is `false` if [models](#models) contains at least one model and `true` otherwise. # PotentialStringReference Source: https://docs.coralos.ai/reference/types/potential-string-reference A string. The string's value can optionally be a reference to a file, URL or constant ## Inline An inline value for a `PotentialStringReference` can be specified as a [string literal](https://toml.io/en/v1.1.0#string): ```toml theme={null} value = "my string value" ``` Or explicitly with a discriminated table. Example using a discriminated [inline table](https://toml.io/en/v1.1.0#inline-table): ```toml theme={null} value = { type = "string", value = "my string value" } ``` ## File File references may be used to define the value of a `PotentialStringReference`. File references will be resolved by the Coral server, relative to the `coral-agent.toml` file. For example, given the following structure: The value of `README.MD` could be used as a value with this syntax: ```toml theme={null} value = { type = "file", path = "README.MD" } ``` ### Input and output encoding Encoding settings are nested under `input` and `output`; top-level `encoding` and `base64` fields are not the encoding contract. To read a Windows-1251 text file: ```toml theme={null} value.type = "file" value.path = "README.MD" value.input.charset = "windows-1251" ``` `input.base64 = true` decodes base64 before reading text. `output.base64 = true` encodes the resulting value as base64. Each side also accepts `charset`; the default charset is UTF-8. These settings apply to inline strings, files, URLs, and constants. ```toml theme={null} value.type = "file" value.path = "README.MD" value.input.charset = "windows-1251" value.output.charset = "utf-8" value.output.base64 = true ``` Blob defaults use a specialised serializer: inline values are base64 strings, while file and URL references are encoded to base64 by default. See [blob options](/reference/agent/tables/options/blob). ## URL A URL reference uses `url` instead of `path`, with the same `input` and `output` encoding settings: ```toml theme={null} value = { type = "url", url = "https://my-server.com/my-agent/1.0.0/README.MD" } ``` File and URL references are resolved by the server when loading the definition. In contexts where file or URL references are disabled, loading fails rather than forwarding the unresolved reference to the agent. ## Constant references Constant references are a special type of string reference that provides a mechanism for using a Coral server-provided string constant as a value. These are especially useful in prototype runtimes. Constant references can be accessed via name: ```toml theme={null} value.type = "constant" value.name = "PROTOTYPE_DEFAULT_SYSTEM_PROMPT" ``` The following constants are available: `PROTOTYPE_DEFAULT_SYSTEM_PROMPT` The default value for `runtimes.prototype.prompts.system.base` `PROTOTYPE_DEFAULT_LOOP_INITIAL_BASE_PROMPT` The default value for `runtimes.prototype.prompts.loop.initial.base` `PROTOTYPE_DEFAULT_LOOP_FOLLOWUP_PROMPT` The default value for `runtimes.prototype.prompts.loop.followup` `CORAL_STATE_RESOURCE_URI` The MCP URI for the Coral state resource `CORAL_INSTRUCTION_RESOURCE_URI` The MCP URI for the Coral instruction resource # Welcome to the CoralOS documentation Source: https://docs.coralos.ai/welcome The decentralized protocol powering AI agent collaboration, trust, and payments.
# CoralOS
Kubernetes for AI agents: a platform for everything between your agents and production - registry, runtimes, security, and orchestration.